Класс QCborValue

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

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

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

Типы

Общедоступные функции

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

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

Этот класс может использоваться для хранения одного из многих типов, доступных в CBOR. CBOR — это компактная двоичная форма представления объектов, которая является надмножеством JSON. Она была создана рабочей группой IETF Constrained RESTful Environments (CoRE), которая использовала её во многих новых RFC. Она предназначена для использования вместе с протоколом CoAP.

CBOR имеет три группы встроенных типов:

• Базовые типы: целые числа, числа с плавающей точкой (double), boolean, 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());

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

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

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

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

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

Такие значения полностью допустимы и могут появляться в CBOR-потоках, в отличие от JSON-содержимого и QJsonValue неопределённого бита. Но, как и undefined QJsonValue, он возвращается методом value() или константным оператором [] контейнера CBOR при некорректных обращениях (индекс вне диапазона для QCborArray, или ключ не найден для QCborMap). Невозможно отличить такой случай от значения Undefined, поэтому, если это необходимо, проверьте размер QCborArray и используйте API итератора QCborMap.

Простые типы

CBOR поддерживает дополнительные простые типы, которые, как Null и Undefined, не несут никакого другого значения. Они называются взаимозаменяемо «Простые типы» и «Простые значения». CBOR кодирует булевы значения как два разных типа (один для true и один для false), но QCborValue имеет удобный API для них.

В настоящее время нет других определённых простых типов CBOR. QCborValue поддерживает их просто по их номеру с API, как isSimpleType() и toSimpleType(), доступными для совместимости с будущими спецификациями до обновления API Qt. Использование их до такой спецификации не рекомендуется, так как другие реализации CBOR могут не поддерживать их полностью.

Поддержка CBOR

QCborValue поддерживает все функции CBOR, необходимые для создания канонических и строгих потоков. Она реализует практически все функции, указанные в RFC 7049.

В следующей таблице перечислены функции CBOR, которые поддерживает QCborValue.

Целые числа в QCborValue ограничены диапазоном типа qint64. То есть, от -9 223 372 036 854 775 808 (-2⁶³) до 9 223 372 036 854 775 807 (2⁶³ - 1). Сам CBOR может представлять целые значения вне этого диапазона, которых QCborValue не поддерживает. При декодировании потока с помощью fromCbor() содержащего одно из таких значений, QCborValue автоматически преобразует его в Double, но это может привести к потере до 11 бит точности.

fromCbor() может декодировать фрагментированные строки, но всегда объединяет фрагменты в одну QCborValue. По этой причине, он всегда записывает нефрагментированные строки при использовании toCbor() (что необходимо для канонического формата).

QCborValue всегда преобразует значения с одинарной и двойной точностью с плавающей запятой в потоке CBOR в значения двойной точности. Функция toCbor() может принимать параметр, указывающий на необходимость их восстановления.

QCborValueRef

QCborValueRef — вспомогательный класс для QCborArray и QCborMap. Он используется при использовании изменяющих API в этих классах. В отличие от QCborValue, в этот класс можно присваивать новые значения. Когда это делается, массив или карта, на которые он ссылается, будут изменены с новым значением. Во всех других аспектах его API идентичен QCborValue.

QJsonValue, QJsonDocument

См. также QCborArray, QCborMap, QCborStreamReader и QCborStreamWriter.

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

enum QCborValue::DiagnosticNotationOptionflags QCborValue::DiagnosticNotationOptions

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

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

Тип DiagnosticNotationOptions является псевдонимом для QFlags<DiagnosticNotationOption>. Он хранит комбинацию значений DiagnosticNotationOption, полученную с помощью оператора OR.

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

enum QCborValue::EncodingOptionflags QCborValue::EncodingOptions

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

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

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

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

enum QCborValue::Type

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QCborValue::QCborValue(QCborValue &&other)

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

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

QCborValue::QCborValue(const QCborValue &other)

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

QCborValue::QCborValue(const QUuid &uuid)

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

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

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

QCborValue::QCborValue(const QRegularExpression &rx)

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

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

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

QCborValue::QCborValue(const QUrl &url)

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

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

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

QCborValue::QCborValue(const QDateTime &dt)

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

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

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

QCborValue::QCborValue(QLatin1String s)

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

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

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

QCborValue::QCborValue(QStringView s)

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

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

QCborValue::QCborValue(const QString &s)

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

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

QCborValue::QCborValue(const QByteArray &ba)

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

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

QCborValue::QCborValue(QCborSimpleType st)

Создаёт QCborValue простого типа st. Тип можно получить позднее с помощью toSimpleType() и isSimpleType(st).

Простые типы CBOR — это типы, не имеющие связанного значения, такие как тип C++ std::nullptr_t, единственное возможное значение которого — 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 boolean представлены парой типов, один для 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. Из-за этого QCborValues с неопределёнными значениями также вернут true для isSimpleType() и isSimpleType(QCborSimpleType::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, раздел 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 рекомендуется тщательно кодировать каждое значение, чтобы избежать потери представления.

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

Если QVariant::isNull() возвращает true, возвращается или вставляется null 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 не является ни одного действительного типа. Недействительные QCborValues отличаются от значений с неопределёнными значениями и обычно представляют ошибку декодирования.

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

bool QCborValue::isMap() const

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

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

bool QCborValue::isNull() const

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

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

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

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

bool QCborValue::isRegularExpression() const

Возвращает true, если этот QCborValue содержит шаблон регулярного выражения. Шаблон можно получить с помощью toRegularExpression().

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

bool QCborValue::isSimpleType() const

Возвращает true, если данный QCborValue относится к одному из простых типов CBOR. Тип можно получить позднее с помощью type(), даже для типов, для которых нет перечисления в API. Также их можно проверить с помощью перегрузки isSimpleType(QCborSimpleType).

См. также QCborSimpleType, isSimpleType(QCborSimpleType) и toSimpleType().

bool QCborValue::isSimpleType(QCborSimpleType st) const

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

Возвращает true, если этот QCborValue является простым типом и toSimpleType() вернёт st, в противном случае — false. Этот метод может быть использован для проверки любого простого типа CBOR, даже тех, для которых нет перечисления в API. Например, для простого типа со значением 12 можно написать:

    value.isSimpleType(QCborSimpleType(12));

См. также QCborValue::QCborValue(QCborSimpleType), isSimpleType(), isFalse(), isTrue(), isNull, isUndefined() и toSimpleType().

bool QCborValue::isString() const

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

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

bool QCborValue::isTag() const

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

Этот метод также возвращает true для расширенных типов, которые распознаёт API. Для кода, обрабатывающего расширенные типы до обновления Qt API для их поддержки, можно восстановить пару тег + значение с тегом, используя taggedValue().

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

bool QCborValue::isTrue() const

Возвращает true, если этот QCborValue — булево значение true. Данный метод существует, потому что внутренне булевы значения CBOR хранятся как два отдельных типа, один для false и один для true.

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

bool QCborValue::isUndefined() const

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

Значения 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, если он имеет тип bool. В противном случае возвращает 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 может использоваться несколькими QCborValues, например, для кодирования разных элементов в более крупном массиве.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QJsonValue QCborValue::toJsonValue() const

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

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

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

Если этот QCborValue содержит значение undefined, эта функция вернёт также undefined QJsonValue. Обратите внимание, что JSON не поддерживает значения undefined, и undefined QJsonValues являются расширением спецификации. Они не могут храниться в QJsonArray или QJsonObject, но могут быть возвращены функциями для обозначения ошибки. Во всех остальных случаях они аналогичны null.

Специальная обработка тегов и расширенных типов

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

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

QRegularExpression QCborValue::toRegularExpression(const QRegularExpression &defaultValue = {}) const

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

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

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

QCborSimpleType QCborValue::toSimpleType(QCborSimpleType defaultValue = QCborSimpleType::Undefined) const

Возвращает тип этого QCborValue, если он является простым типом. Если это не простой тип, возвращает defaultValue.

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

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

QString QCborValue::toString(const QString &defaultValue = {}) const

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

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

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

QUrl QCborValue::toUrl(const QUrl &defaultValue = {}) const

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

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

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

QUuid QCborValue::toUuid(const QUuid &defaultValue = {}) const

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

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

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

QVariant QCborValue::toVariant() const

Преобразует это значение в родной тип Qt и возвращает соответствующий QVariant.

В следующей таблице показано отображение между типами QCborValue и метатипами Qt.

Обратите внимание, что значения как в CBOR-словарях, так и в CBOR-массивах также рекурсивно преобразуются с помощью этой функции и помещаются в QVariantMap и QVariantList соответственно. Вы не найдёте QCborMap и QCborArray, хранящиеся внутри QVariant.

QVariantMap имеют строковые ключи, в отличие от CBOR, поэтому преобразование QCborMap в QVariantMap подразумевает этап «строкового» преобразования значений ключей. Подробнее см. QCborMap::toJsonObject().

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

QCborValue::Type QCborValue::type() const

Возвращает тип этого QCborValue. Тип также можно получить позже с помощью одной из функций «isXxx».

См. также isInteger(), isByteArray(), isString(), isArray(), isMap(), isTag(), isFalse(), isTrue(), isBool(), isNull(), isUndefined(), isDouble(), isDateTime(), isUrl(), isRegularExpression() и isUuid().

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

Сравнивает это значение и other и возвращает true, если содержимое отличается, false в противном случае. Если каждый QCborValue содержит массив или словарь, сравнение происходит рекурсивно по элементам, содержащимся в них.

Дополнительную информацию о равенстве CBOR в Qt см. в QCborValue::compare().

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

bool QCborValue::operator<(const QCborValue &other) const

Сравнивает это значение и other и возвращает true, если это значение должно быть отсортировано перед other, false в противном случае. Если каждый QCborValue содержит массив или словарь, сравнение происходит рекурсивно по элементам, содержащимся в них.

Дополнительную информацию о порядке сортировки CBOR см. в QCborValue::compare().

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

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

Сравнивает это значение и other и возвращает true, если они содержат одинаковое содержимое, false в противном случае. Если каждый QCborValue содержит массив или словарь, сравнение происходит рекурсивно по элементам, содержащимся в них.

Дополнительную информацию о равенстве CBOR в Qt см. в compare().

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

const QCborValue QCborValue::operator[](const QString &key) const

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

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

    value.toMap().value(key);

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

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

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

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

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

    value.toMap().value(key);

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

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

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

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

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

QCborValueRef QCborValue::operator[](qint64 key)

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

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

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

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

QCborValueRef QCborValue::operator[](QLatin1String key)

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

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