QUrl Class

メンバ関数のドキュメント

QUrl::QUrl()

空の QUrl オブジェクトを作成します。

QUrl::QUrl(const QString &url, QUrl::ParsingMode parsingMode = TolerantMode)

url を解析して URL を構築します。このコンストラクタは、適切な URL または URL リファレンスを受け取ることを前提としており、意図を推測しようとはしません。たとえば、次のような宣言：

QUrl url("example.com");

これは有効なURLを生成しますが、入力の「scheme()」部分が欠落しているため、期待通りの結果にならない可能性があります。上記のような文字列の場合、アプリケーションでは `fromUserInput()` を使用することを推奨します。このコンストラクタや `setUrl()` を使用する場合、おそらく意図されていたのは次のようなものです:

QUrl url("https://example.com");

QUrlは、URLで許可されていないすべての文字を自動的にパーセントエンコードし、非予約文字（英字、数字、ハイフン、アンダースコア、ドット、チルダ）を表すパーセントエンコードされた文字列をデコードします。それ以外の文字はすべて元の形式のまま残されます。

パーサーモードparsingMode を使用して、url を解析します。TolerantMode （デフォルト）では、QUrl は特定の誤り（特に、2 桁の 16 進数に続かないパーセント記号 ('%') の存在など）を修正し、どの位置にある文字でも受け入れます。StrictMode では、エンコーディングの誤りは許容されず、QUrlは特定の禁止文字がエンコードされていない状態で含まれていないかについてもチェックします。StrictMode でエラーが検出された場合、isValid()はfalseを返します。このコンテキストでは、解析モードDecodedMode は使用できません。

例：

QUrl url("http://www.example.com/List of holidays.xml");
// url.toEncoded() == "http://www.example.com/List%20of%20holidays.xml"

エンコードされた文字列からURLを構築するには、fromEncoded()を使用することもできます：

QUrl url = QUrl::fromEncoded("http://qt-project.org/List%20of%20holidays.xml");

どちらの関数も同等の機能を持ち、Qt 5 ではどちらもエンコードされたデータを受け入れます。通常、QUrl コンストラクタまたはsetUrl() とfromEncoded() のどちらを使用するかは、ソースデータによって決まります。コンストラクタとsetUrl() はQString を受け取りますが、fromEncoded はQByteArray を受け取ります。

setUrl()、fromEncoded()、およびTolerantModeも参照してください 。

[noexcept] QUrl::QUrl(const QUrl &other)

other のコピーを作成します。

[noexcept] QUrl::QUrl(QUrl &&other)

QUrlインスタンスをムーブコンストラクトし、other が指していたのと同じオブジェクトを指すようにします。

[noexcept] QUrl::~QUrl()

デストラクタ。オブジェクトが削除される直前に呼び出されます。

QUrl QUrl::adjusted(QUrl::FormattingOptions options) const

調整済みのURLを返します。options にフラグを渡すことで、出力をカスタマイズできます。

QUrl::ComponentFormattingOption のエンコーディングオプションは、このメソッドではあまり意味を成しません。QUrl::PreferLocalFile も同様です。

これは常に `QUrl(url.toString(options))` と同等です。

FormattingOptions 、toEncoded()、およびtoString()も参照してください 。

QString QUrl::authority(QUrl::ComponentFormattingOptions options = PrettyDecoded) const

URL に権限が定義されている場合はその権限を返し、定義されていない場合は空文字列を返します。

この関数は、曖昧さのない値を返します。この値には、依然としてパーセントエンコードされた文字や、QString でデコードされた形式では表現できない一部の制御シーケンスが含まれる場合があります。

options 引数は、ユーザー情報コンポーネントのフォーマット方法を制御します。この関数では、QUrl::FullyDecoded の値は使用できません。完全にデコードされたデータを取得する必要がある場合は、userName()、password()、host()、およびport()を個別に呼び出してください。

setAuthority()、userInfo()、userName()、password()、host()、およびport()も参照してください 。

void QUrl::clear()

QUrl の内容をリセットします。この関数を呼び出した後、QUrl は、デフォルトの空コンストラクタで生成されたものと同じ状態になります。

isEmpty()も参照してください 。

QString QUrl::errorString() const

このQUrl オブジェクトを最後に変更した操作で構文解析エラーが発生した場合、エラーメッセージを返します。エラーが検出されなかった場合、この関数は空の文字列を返し、isValid()はtrue を返します。

この関数が返すエラーメッセージは技術的なものであり、エンドユーザーには理解できない場合があります。主に、QUrl が特定の入力を受け付けない理由を理解しようとする開発者にとって有用です。

QUrl::ParsingModeも参照してください 。

QString QUrl::fileName(QUrl::ComponentFormattingOptions options = FullyDecoded) const

ディレクトリパスを除いたファイル名を返します。

なお、このQUrl オブジェクトにスラッシュで終わるパスが指定された場合、ファイル名は空とみなされます。

パスにスラッシュが含まれていない場合は、そのパス全体が fileName として返されます。

例:

QUrl url("http://qt-project.org/support/file.html");
// url.adjusted(RemoveFilename) == "http://qt-project.org/support/"
// url.fileName() == "file.html"

options 引数は、ファイル名コンポーネントのフォーマット方法を制御します。どの値を使用しても、曖昧さのない結果が得られます。QUrl::FullyDecoded を指定すると、すべてのパーセントエンコードされた文字列がデコードされます。それ以外の場合、QString でデコードされた形式で表現できない一部の制御シーケンスに対して、返される値にパーセントエンコードされた文字列が含まれることがあります。

path()も参照してください 。

QString QUrl::fragment(QUrl::ComponentFormattingOptions options = PrettyDecoded) const

URLのフラグメントを返します。解析されたURLにフラグメントが含まれているかどうかを確認するには、hasFragment() を使用してください。

options 引数は、フラグメント部分のフォーマット方法を制御します。どの値を使用しても、曖昧さのない結果が得られます。QUrl::FullyDecoded を指定すると、すべてのパーセントエンコードされたシーケンスがデコードされます。それ以外の場合、QString でデコード形式で表現できない一部の制御シーケンスに対して、返される値にパーセントエンコードされたシーケンスが含まれる可能性があります。

なお、QUrl::FullyDecoded を指定すると、表現不可能なシーケンスが存在する場合、データが失われる可能性があります。この値は、結果が URL 以外のコンテキストで使用される場合に使用することを推奨します。

setFragment() およびhasFragment()も参照してください 。

[static, since 6.3] QString QUrl::fromAce(const QByteArray &domain, QUrl::AceProcessingOptions options = {})

指定されたドメイン名domain のUnicode形式を返します。このドメイン名はASCII互換エンコーディング（ACE）でエンコードされています。options にフラグを渡すことで、出力をカスタマイズできます。この関数の結果は、domain と同等とみなされます。

domain の値がエンコードできない場合、その値はQString に変換されて返されます。

ASCII互換エンコーディング（ACE）は、RFC 3490、RFC 3491、およびRFC 3492で定義されており、Unicode Technical Standard #46によって更新されています。 これは、アプリケーションにおけるドメイン名の国際化 (IDNA) 仕様の一部であり、これにより、"example.com" のようなドメイン名を非 US-ASCII 文字を使用して記述することが可能になります。

この関数は Qt 6.3 で導入されました。

[static] QUrl QUrl::fromCFURL(CFURLRef url)

CFURLurl のコピーを含む `QUrl ` オブジェクトを作成します。

[static] QUrl QUrl::fromEncoded(QByteArrayView input, QUrl::ParsingMode mode = TolerantMode)

input を解析し、対応するQUrl を返します。input はエンコードされた形式であり、ASCII 文字のみが含まれているものとみなされます。

mode を使用して URL を解析します。このパラメータの詳細については、setUrl() を参照してください。このコンテキストでは、QUrl::DecodedMode は使用できません。

toEncoded() およびsetUrl()も参照してください 。

[static] QUrl QUrl::fromLocalFile(const QString &localFile)

localFile をローカルファイルとして解釈した、QUrl 形式の表現を返します。この関数は、スラッシュで区切られたパスだけでなく、そのプラットフォーム固有の区切り文字で区切られたパスも受け付けます。

また、この関数は、リモートファイルを示すために先頭にスラッシュ（またはバックスラッシュ）が2つ並んだパス（例：「//servername/path/to/file.txt」）も受け付けます。なお、QFile::open() を使用して実際にこのファイルを開くことができるのは、特定のプラットフォームに限られることに注意してください。

localFile が空の場合、URL は空になります（Qt 5.4 以降）。

qDebug()<<QUrl::fromLocalFile("file.txt");            // QUrl("file:file.txt")
qDebug() << QUrl::fromLocalFile("/home/user/file.txt"); // QUrl("file:///home/user/file.txt")
qDebug() << QUrl::fromLocalFile("file:file.txt");       // doesn't make sense; expects path, not url with scheme

上記のコードスニペットの 1 行目では、ローカルの相対パスからファイル URL が生成されています。相対パスを含むファイル URL が意味を持つのは、それを解決するためのベース URL が存在する場合に限られます。例えば：

QUrl url=QUrl::fromLocalFile("file.txt");
QUrl baseUrl=QUrl("file:/home/user/");
// 誤り：urlにはすでにスキーマが含まれているため、QUrl("file:file.txt")が出力される
qDebug() << baseUrl.resolved(url);

このようなURLを解決するには、あらかじめスキームを削除する必要があります：

// 正しい例: QUrl("file:///home/user/file.txt") を出力する
url.setScheme(QString());
qDebug() << baseUrl.resolved(url);

このため、相対ファイルパスには相対URL（つまり、スキームを指定しない形式）を使用することをお勧めします：

QUrl url=QUrl("file.txt");
QUrl baseUrl=QUrl("file:/home/user/");
// QUrl("file:///home/user/file.txt") を出力します
qDebug() << baseUrl.resolved(url);

toLocalFile()、isLocalFile()、およびQDir::toNativeSeparators()も参照してください 。

[static] QUrl QUrl::fromNSURL(const NSURL *url)

NSURLurl のコピーを含むQUrl を生成します。

[static] QString QUrl::fromPercentEncoding(const QByteArray &input)

input のデコード済みコピーを返します。input は、まずパーセントエンコーディングからデコードされ、その後UTF-8からUnicodeに変換されます。

[static] QList<QUrl> QUrl::fromStringList(const QStringList &urls, QUrl::ParsingMode mode = TolerantMode)

QUrl （str,mode ）を使用して、urls を表す文字列のリストを URL のリストに変換します。なお、これはすべての文字列が URL でなければならないことを意味し、例えばローカルパスなどは含まれません。

[static] QUrl QUrl::fromUserInput(const QString &userInput, const QString &workingDirectory = QString(), QUrl::UserInputResolutionOptions options = DefaultResolution)

ユーザーが指定したuserInput 文字列から、有効なURLを導き出せる場合はそれを返します。導き出せない場合は、無効なQUrl()を返します。

これにより、ユーザーはURLやローカルファイルのパスをプレーン文字列の形式で入力できるようになります。この文字列は、アドレスバーに手動で入力したり、クリップボードから取得したり、コマンドライン引数として渡したりすることができます。

文字列がまだ有効なURLでない場合、さまざまな仮定に基づいて最適な推測が行われます。

文字列がシステム上の有効なファイルパスに対応している場合、QUrl::fromLocalFile() を使用して file:// URL が構築されます。

そうでない場合は、その文字列を http:// または ftp:// URL に変換しようと試みます。後者は、文字列が 'ftp' で始まる場合に適用されます。その結果はQUrl の許容性の高いパーサーに渡され、成功した場合は有効なQUrl が返され、失敗した場合はQUrl() が返されます。

例：

• qt-project.org は http://qt-project.org になります
• ftp.qt-project.org は ftp://ftp.qt-project.org になります
• hostname は http://hostname になります
• /home/user/test.html は file:///home/user/test.html になります

相対パスを処理できるようにするため、このメソッドはオプションのworkingDirectory パスを引数として受け取ります。これは特に、コマンドライン引数を扱う際に役立ちます。workingDirectory が空の場合、相対パスの処理は行われません。

デフォルトでは、相対パスのように見える入力文字列は、指定された作業ディレクトリにファイルが実際に存在する場合にのみ、相対パスとして扱われます。アプリケーションがまだ存在しないファイルを処理できる場合は、options にAssumeLocalFile フラグを指定する必要があります。

bool QUrl::hasFragment() const

このURLにフラグメントが含まれている場合（つまり、URL内に「#」が含まれている場合）、true を返します。

fragment() およびsetFragment()も参照してください 。

bool QUrl::hasQuery() const

このURLにクエリが含まれている場合（つまり、URL内に「?」が見られた場合）、true を返します。

setQuery()、query()、およびhasFragment()も参照してください 。

QString QUrl::host(QUrl::ComponentFormattingOptions options = FullyDecoded) const

URL が定義されている場合はそのホスト名を返します。定義されていない場合は空の文字列が返されます。

options 引数は、ホスト名の書式を制御します。QUrl::EncodeUnicode オプションを指定すると、この関数はホスト名を ASCII-Compatible Encoding (ACE) 形式で返します。これは、8 ビットクリーンではないチャネルや、レガシーなホスト名を必要とするチャネル（DNS 要求や HTTP リクエストヘッダーなど）での使用に適しています。 このフラグが指定されていない場合、この関数は、許可されたトップレベルドメインのリスト（idnWhitelist() を参照）に従って、Unicode 形式の国際ドメイン名 (IDN) を返します。

その他のフラグはすべて無視されます。ホスト名には制御文字やパーセント記号を含めることはできないため、返される値は完全にデコードされたものとみなすことができます。

setHost()、idnWhitelist()、setIdnWhitelist()、およびauthority()も参照してください 。

[static] QStringList QUrl::idnWhitelist()

構成に非ASCII文字を含めることが許可されているトップレベルドメインの現在のホワイトリストを返します。

このリストの根拠については、setIdnWhitelist() を参照してください。

setIdnWhitelist() およびAceProcessingOptionも参照してください 。

bool QUrl::isEmpty() const

URLにデータが含まれていない場合は `true ` を返し、それ以外の場合は `false` を返します。

clear()も参照してください 。

bool QUrl::isLocalFile() const

このURLがローカルファイルパスを指している場合、true を返します。スキームが「file」である場合、そのURLはローカルファイルパスとみなされます。

なお、この関数では、ホスト名を含む URL であっても、最終的にそのファイルパスがQFile::open() で開けない場合でも、ローカルファイルパスとして扱われることに注意してください。

fromLocalFile() およびtoLocalFile()も参照してください 。

bool QUrl::isParentOf(const QUrl &childUrl) const

このURLがchildUrl の親URLである場合、true を返します。childUrl は、2つのURLが同じスキームとオーソリティを持ち、かつこのURLのパスがchildUrl のパスの親である場合に、このURLの子URLとなります。

bool QUrl::isRelative() const

URLが相対URLの場合はtrue を返し、それ以外の場合はfalse を返します。URLのスキームが未定義の場合、そのURLは相対参照とみなされます。したがって、この関数はscheme()を呼び出すことと同等です。isEmpty()。

相対参照については、RFC 3986 のセクション 4.2 で定義されている。

Relative URLs vs Relative Pathsも参照のこと 。

bool QUrl::isValid() const

URLが空でなく、かつ有効な場合は `true ` を返し、そうでない場合は `false` を返します。

URL に対して適合性テストが実行されます。URL が有効であると判定されるためには、URL のすべての部分が URI 標準のエンコーディング規則に準拠している必要があります。

boolcheckUrl(constQUrl&url) {
    if(!url.isValid()) {
        qDebug("Invalid URL: %s", qUtf8Printable(url.toString()));
       return false;
    }

    return true;
}

bool QUrl::matches(const QUrl &url, QUrl::FormattingOptions options) const

このURLと指定されたurl の両方にoptions を適用した結果が等しい場合、true を返します。そうでない場合は、false を返します。

これは、両方の URL に対してadjusted(options) を呼び出し、結果の URL を比較することと同等ですが、処理が高速です。

QString QUrl::password(QUrl::ComponentFormattingOptions options = FullyDecoded) const

URLにパスワードが定義されている場合はそのパスワードを返し、定義されていない場合は空の文字列を返します。

options 引数は、ユーザー名部分のフォーマット方法を制御します。どの値を設定しても、結果に曖昧さは生じません。QUrl::FullyDecoded を指定すると、すべてのパーセントエンコードされたシーケンスがデコードされます。そうでない場合、QString ではデコード形式で表現できない一部の制御シーケンスに対して、返される値にパーセントエンコードされたシーケンスが含まれる可能性があります。

なお、QUrl::FullyDecoded を使用すると、表現不可能なシーケンスが存在する場合にデータが失われる可能性があることに注意してください。この値は、QAuthenticator での設定やログインのネゴシエーションなど、URL以外のコンテキストで結果が使用される場合に使用することを推奨します。

setPassword()も参照してください 。

QString QUrl::path(QUrl::ComponentFormattingOptions options = FullyDecoded) const

URLのパスを返します。

qDebug()<<QUrl("file:file.txt").path();                   // "file.txt"
qDebug() << QUrl("/home/user/file.txt").path();             // "/home/user/file.txt"
qDebug() << QUrl("http://www.example.com/test/123").path(); // "/test/123"

options 引数は、パス構成要素のフォーマット方法を制御します。どの値を設定しても、曖昧さのない結果が得られます。QUrl::FullyDecoded を指定すると、すべてのパーセントエンコードされた文字列がデコードされます。それ以外の場合、QString でデコードされた形式では表現できない一部の制御文字列に対して、返される値にパーセントエンコードされた文字列が含まれることがあります。

なお、QUrl::FullyDecoded を指定すると、表現不可能なシーケンスが存在する場合、データが失われる可能性があります。この値を使用するのは、FTPサーバーへの送信など、URL以外のコンテキストで結果が使用される場合を推奨します。

データ損失の例としては、Unicode以外のパーセントエンコードされたシーケンスが存在し、FullyDecoded （デフォルト）が使用された場合が挙げられます。

qDebug() << QUrl("/foo%FFbar").path();

この例では、%FF は変換できないため、ある程度のデータ損失が生じます。

また、パスにサブ区切り記号（+ など）が含まれている場合にも、データ損失が発生する可能性があります：

qDebug() << QUrl("/foo+bar%2B").path(); // "/foo+bar+"

その他のデコード例：

constQUrl url("/tmp/Mambo %235%3F.mp3");
qDebug() << url.path(QUrl::FullyDecoded);  // "/tmp/Mambo #5?.mp3"
qDebug() << url.path(QUrl::PrettyDecoded); // "/tmp/Mambo #5?.mp3"
qDebug() << url.path(QUrl::FullyEncoded);  // "/tmp/Mambo%20%235%3F.mp3"

「setPath()」も参照してください 。

int QUrl::port(int defaultPort = -1) const

URLのポートを返します。ポートが指定されていない場合は、defaultPort を返します。

例:

QTcpSocket sock;
sock.connectToHost(url.host(), url.port(80));

関連項目: setPort()。

QString QUrl::query(QUrl::ComponentFormattingOptions options = PrettyDecoded) const

クエリ文字列が存在する場合はそのURLのクエリ文字列を返し、存在しない場合は空の結果を返します。解析されたURLにクエリ文字列が含まれているかどうかを確認するには、hasQuery() を使用してください。

options 引数は、クエリコンポーネントのフォーマット方法を制御します。どの値を使用しても、曖昧さのない結果が得られます。QUrl::FullyDecoded を指定すると、すべてのパーセントエンコードされたシーケンスがデコードされます。それ以外の場合、QString ではデコード形式で表現できない一部の制御シーケンスについて、返される値にパーセントエンコードされたシーケンスが含まれる可能性があります。

なお、クエリ内での `QUrl::FullyDecoded ` の使用は推奨されません。クエリには、プラス記号（'+'）を表す「%2B」シーケンスなど、パーセントエンコードされたままにしておくべきデータが含まれている場合が多いためです。

setQuery() およびhasQuery()も参照してください 。

QUrl QUrl::resolved(const QUrl &relative) const

このURLとrelative を結合した結果を返します。このURLは、relative を絶対URLに変換するためのベースとして使用されます。

relative が相対 URL でない場合、この関数はrelative をそのまま返します。それ以外の場合は、2 つの URL のパスが結合され、次の例のように、ベース URL のスキーマとオーソリティを持ち、結合されたパスを備えた新しい URL が返されます：

QUrl baseUrl("http://qt.digia.com/Support/");
QUrl relativeUrl("../Product/Library/");
qDebug(qUtf8Printable(baseUrl.resolved(relativeUrl).toString()));
// 「http://qt.digia.com/Product/Library/」と出力される

".." を引数として resolved() を呼び出すと、元のパスより 1 レベル上のディレクトリを持つQUrl が返されます。同様に、"../.." を引数として resolved() を呼び出すと、パスから 2 レベル分が削除されます。relative が "/" の場合、パスは "/" になります。

isRelative()も参照してください 。

QString QUrl::scheme() const

URL のスキームを返します。空の文字列が返された場合、スキームは未定義であり、その URL は相対 URL であることを意味します。

スキームには US-ASCII の英字または数字のみを含めることができます。つまり、エンコードを必要とする文字は含めることができません。また、スキームは常に小文字で返されます。

setScheme() およびisRelative()も参照してください 。

void QUrl::setAuthority(const QString &authority, QUrl::ParsingMode mode = TolerantMode)

URLのオーソリティを「authority 」に設定します。

URLのオーソリティとは、ユーザー情報、ホスト名、およびポートの組み合わせを指します。これらの要素はすべてオプションであるため、空のオーソリティも有効です。

ユーザー情報とホスト名は「@」で区切られ、ホスト名とポートは「:」で区切られます。ユーザー情報が空の場合、「@」は省略する必要があります。ただし、ポートが空の場合、余分な「:」が含まれていても許容されます。

以下の例は、有効なオーソリティ文字列を示しています：

authority のデータは、mode に従って解釈されます。StrictMode では、'%'文字の後に必ず2文字の16進数が続く必要があり、一部の文字（スペースを含む）はデコードされていない形式では使用できません。TolerantMode （デフォルト）では、すべての文字が未デコードの形式で受け入れられ、寛容なパーサーが、2つの16進文字が続かない余分な「%」を修正します。

この関数では、mode をQUrl::DecodedMode とすることはできません。完全にデコードされたデータを設定するには、setUserName()、setPassword()、setHost()、setPort() を個別に呼び出してください。

authority()、setUserInfo()、setHost()、およびsetPort()も参照してください 。

void QUrl::setFragment(const QString &fragment, QUrl::ParsingMode mode = TolerantMode)

URLのフラグメントをfragment に設定します。フラグメントとは、URLの最後の部分であり、「#」の後に文字列が続く形で表されます。これは通常、HTTPにおいて、ページ上の特定のリンクや位置を指すために使用されます：

フラグメントは、URLの「参照」と呼ばれることもあります。

QString()（nullのQString ）を引数として渡すと、フラグメントが解除されます。QString （""）（空だがnullではないQString ）を引数として渡すと、フラグメントが空文字列に設定されます（元のURLに「#」が1つだけあるかのように）。

fragment のデータは、mode に従って解釈されます。StrictMode では、'%'文字の後に必ず2文字の16進数が続く必要があり、一部の文字（スペースを含む）は未デコードの形式では使用できません。TolerantMode では、すべての文字が未デコードの形式で受け入れられ、寛容なパーサーが、2文字の16進数が続かない余分な'%'を修正します。DecodedMode では、「%」はそのままの文字として扱われ、エンコードされた文字は使用できません。

QUrl::DecodedMode URL 以外のデータソースからフラグメントを設定する場合、またはQUrl::FullyDecoded フォーマットオプションを指定してfragment() を呼び出して取得したフラグメントを使用する場合は、これを使用する必要があります。

fragment() およびhasFragment()も参照してください 。

void QUrl::setHost(const QString &host, QUrl::ParsingMode mode = DecodedMode)

URLのホストをhost に設定します。ホストはオーソリティの一部です。

host のデータは、mode に基づいて解釈されます。StrictMode では、'%' 文字の後に必ず 2 文字の 16 進数が続く必要があり、一部の文字（スペースを含む）はデコードされていない形式では使用できません。TolerantMode では、すべての文字がデコードされていない形式で受け入れられ、許容性の高いパーサーが、2 文字の 16 進数が続かない余分な '%' を修正します。DecodedMode では、「%」はそれ自体を表し、エンコードされた文字は使用できません。

いずれの場合も、解析結果は、国際化リソース識別子仕様（RFC 3987）によって修正された STD 3 の規則に準拠した有効なホスト名でなければならないことに注意してください。無効なホスト名は許可されず、isValid() の評価結果が false になります。

host() およびsetAuthority()も参照してください 。

[static] void QUrl::setIdnWhitelist(const QStringList &list)

ドメイン名に非ASCII文字の使用が許可されるトップレベルドメイン（TLD）のホワイトリストを、list の値に設定します。

なお、この関数を呼び出す場合は、idnWhitelist() にアクセスする可能性のあるスレッドを起動する前に実行する必要があります。

Qt には、国際化ドメイン名 (IDN) のサポートが公表されているインターネットのトップレベルドメインと、見た目が似ている文字（たとえば、ラテン文字の小文字「'a' 」と、ほとんどのフォントで視覚的に区別がつかないキリル文字の同等の文字）の間で混同が生じないことを保証するためのルールが記載されたデフォルトのリストが付属しています。

レジストラが新しいルールを公表するにつれて、このリストは定期的に更新されます。

この関数は、TLD を追加または削除するためにリストを操作する必要があるユーザー向けに提供されています。テスト以外の目的でこの関数の値を変更することは、ユーザーをセキュリティリスクにさらす可能性があるため、推奨されません。

idnWhitelist()も参照してください 。

void QUrl::setPassword(const QString &password, QUrl::ParsingMode mode = DecodedMode)

URLのパスワードをpassword に設定します。password は、setUserInfo()に記載されているように、URLの権限（authority）内のユーザー情報要素の一部です。

password のデータは、mode に基づいて解釈されます。StrictMode では、'%' 文字の直後に必ず 2 文字の 16 進数が続く必要があり、一部の文字（スペースを含む）はデコードされていない形式では使用できません。TolerantMode では、すべての文字がデコードされていない形式で受け入れられ、寛容なパーサーが 2 文字の 16 進数が続いていない不要な '%' を修正します。DecodedMode では、「%」はそのままの文字として扱われ、エンコードされた文字は使用できません。

QUrl::DecodedMode これは、URL ではないデータソース（ユーザーに表示されるパスワードダイアログや、QUrl::FullyDecoded フォーマットオプションを指定してpassword() を呼び出して取得したパスワードなど）からパスワードを設定する際に使用する必要があります。

password() およびsetUserInfo()も参照してください 。

void QUrl::setPath(const QString &path, QUrl::ParsingMode mode = DecodedMode)

URLのパスを `path` に設定します。パスとは、URLにおいて「authority」の直後からクエリ文字列の直前に至る部分のことです。

非階層型スキームの場合、パスは次の例のように、スキーム宣言の後に続くすべての内容となります：

path のデータは、mode に基づいて解釈されます。StrictMode では、'%' 文字の後に必ず 2 文字の 16 進数が続く必要があり、一部の文字（スペースを含む）は未デコードの形式では使用できません。TolerantMode では、すべての文字が未デコードの形式で受け入れられ、寛容なパーサーが 2 文字の 16 進数が続かない余分な '%' を修正します。DecodedMode では、「%」はそれ自体を表し、エンコードされた文字は使用できません。

QUrl::DecodedMode これは、ユーザーに表示されるダイアログや、QUrl::FullyDecoded フォーマットオプションを指定してpath()を呼び出して取得したパスなど、URLではないデータソースからパスを設定する際に使用する必要があります。

path()も参照してください 。

void QUrl::setPort(int port)

URLのポートをport に設定します。setAuthority()で説明されているように、ポートはURLの権限の一部です。

port 値は0から65535までの範囲でなければなりません。ポートを-1に設定すると、ポートが未指定であることを示します。

port()も参照してください 。

void QUrl::setQuery(const QString &query, QUrl::ParsingMode mode = TolerantMode)

URLのクエリ文字列を「query 」に設定します。

この関数は、キーと値のパターンに当てはまらないクエリ文字列を渡す必要がある場合や、QUrl で推奨されているものとは異なる方式で特殊文字をエンコードしているクエリ文字列を渡す必要がある場合に役立ちます。

query に QString()（QString の null 値）を渡すと、クエリは完全に解除されます。ただし、QString （"") を渡すと、元の URL に「?」が 1 つだけあるかのように、クエリは空の値に設定されます。

query のデータは、mode に従って解釈されます。StrictMode では、'%'文字の後に必ず2文字の16進数が続く必要があり、一部の文字（スペースを含む）は未デコードの形式では使用できません。TolerantMode では、すべての文字が未デコードの形式で受け入れられ、寛容なパーサーが、2文字の16進数が続かない余分な'%'を修正します。DecodedMode では、「%」はそのままの文字として扱われ、エンコードされた文字は使用できません。

クエリ文字列にはパーセントエンコードされたシーケンスが含まれることが多いため、DecodedMode の使用は推奨されません。注意すべき特別なシーケンスとして、プラス記号（'+'）があります。QUrl は、Webブラウザから送信されるHTMLフォームではスペースがプラス記号に変換されるのに対し、スペースをプラス記号に変換しません。 クエリ内で実際のプラス記号を表すには、通常「%2B」というシーケンスが使用されます。この関数は、TolerantMode またはStrictMode 内で「%2B」シーケンスをそのまま残します。

query() およびhasQuery()も参照してください 。

void QUrl::setQuery(const QUrlQuery &query)

URLのクエリ文字列をquery に設定します。

この関数は、QUrlQuery オブジェクトからクエリ文字列を再構築し、このQUrl オブジェクトに設定します。QUrlQuery にはすでに解析済みのデータが含まれているため、この関数には解析パラメータはありません。

query() およびhasQuery()も参照してください 。

void QUrl::setScheme(const QString &scheme)

URLのスキームを `scheme` に設定します。スキームにはASCII文字のみを含めることができるため、入力に対して変換やデコードは行われません。また、スキームはASCII文字のアルファベットで始まる必要があります。

スキームは、URL の種類（またはプロトコル）を表します。これは、URL の先頭にある 1 文字以上の ASCII 文字によって表されます。

スキームはRFC 3986に厳密に準拠しています：scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )

次の例は、スキーマが「ftp」であるURLを示しています：

スキームを設定するには、次の呼び出しを使用します:

QUrl url;
url.setScheme("ftp");

スキームを空にすることも可能です。その場合、URLは相対パスとして解釈されます。

scheme() およびisRelative()も参照してください 。

void QUrl::setUrl(const QString &url, QUrl::ParsingMode parsingMode = TolerantMode)

url を解析し、このオブジェクトをその値に設定します。QUrl は、URL で使用が許可されていないすべての文字を自動的にパーセントエンコードし、予約されていない文字（英字、数字、ハイフン、アンダースコア、ドット、チルダ）を表すパーセントエンコードされた文字列をデコードします。それ以外の文字はすべて元のまま残されます。

url を、パーサーモードparsingMode を使用して解析します。TolerantMode （デフォルト）では、QUrl は特定の誤り（特に、2桁の16進数に続かないパーセント記号（'%'）の存在など）を修正し、どの位置にあるどの文字でも受け入れます。StrictMode では、エンコーディングの誤りは許容されず、QUrl は、特定の禁止文字がエンコードされていない形で含まれていないかどうかもチェックします。StrictMode でエラーが検出された場合、isValid() は false を返します。パーサーモードDecodedMode はこのコンテキストでは許可されておらず、実行時の警告が発生します。

url() およびtoString()も参照してください 。

void QUrl::setUserInfo(const QString &userInfo, QUrl::ParsingMode mode = TolerantMode)

URLのユーザー情報をuserInfo に設定します。ユーザー情報は、setAuthority()で説明されているように、URLの権限におけるオプションの部分です。

ユーザー情報は、ユーザー名と（任意の）パスワードで構成され、「:」で区切られます。パスワードが空の場合は、コロンを省略する必要があります。以下の例は、有効なユーザー情報文字列を示しています：

userInfo のデータは、mode に基づいて解釈されます。StrictMode では、'%' 文字の後に正確に 2 文字の 16 進数が続く必要があり、一部の文字（スペースを含む）はデコードされていない形式では使用できません。TolerantMode （デフォルト）では、すべての文字が未デコードの形式で受け入れられ、寛容なパーサーが、2 文字の 16 進数に続かない余分な '%' を修正します。

この関数では、mode をQUrl::DecodedMode とすることはできません。完全にデコードされたデータを設定するには、setUserName() とsetPassword() を個別に呼び出してください。

userInfo()、setUserName()、setPassword()、およびsetAuthority()も参照してください 。

void QUrl::setUserName(const QString &userName, QUrl::ParsingMode mode = DecodedMode)

URLのユーザー名をuserName に設定します。userName は、setUserInfo() に記載されているとおり、URLの権威（authority）内のuser info要素の一部です。

userName のデータは、mode に基づいて解釈されます。StrictMode では、'%' 文字の直後に必ず 2 文字の 16 進数が続く必要があり、一部の文字（スペースを含む）はデコードされていない形式では使用できません。TolerantMode （デフォルト）では、すべての文字が未エンコードの形で受け入れられ、寛容なパーサーが、2 文字の 16 進数に続かない余分な '%' を修正します。DecodedMode では、'%' はその文字自体を表し、エンコードされた文字は使用できません。

QUrl::DecodedMode この設定は、URL ではないデータソース（ユーザーに表示されるパスワードダイアログや、QUrl::FullyDecoded フォーマットオプションを指定してuserName() を呼び出した際に取得したユーザー名など）からユーザー名を設定する場合に使用すべきです。

userName() およびsetUserInfo()も参照してください 。

[noexcept] void QUrl::swap(QUrl &other)

このURLをother と置き換えます。この処理は非常に高速で、失敗することはありません。

[static, since 6.3] QByteArray QUrl::toAce(const QString &domain, QUrl::AceProcessingOptions options = {})

指定されたドメイン名 `domain` のASCII互換エンコーディングを返します。options にフラグを指定することで、出力をカスタマイズできます。この関数の結果は、`domain` と同等とみなされます。

ASCII互換エンコーディング（ACE）は、RFC 3490、RFC 3491、およびRFC 3492によって定義され、Unicode Technical Standard #46によって更新されています。 これは、アプリケーションにおけるドメイン名の国際化（IDNA）仕様の一部であり、これにより、"example.com" のようなドメイン名を非US-ASCII文字を使用して記述することが可能になります。

domain が有効なホスト名でない場合、この関数は空のQByteArray を返します。特に、IPv6 リテラルは有効なドメイン名ではないことに注意してください。

この関数は Qt 6.3 で導入されました。

CFURLRef QUrl::toCFURL() const

QUrl から CFURL を作成します。

CFURLの所有権は呼び出し元にあり、その解放も呼び出し元の責任となります。

QString QUrl::toDisplayString(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const

URLを人間が読みやすい文字列形式で返します。options でフラグを指定することで、出力内容をカスタマイズできます。パスワードは決してユーザーに表示してはならないため、RemovePassword オプションは常に有効になっています。

デフォルトのオプションでは、結果として得られるQString を後でQUrl に再度渡すことができますが、当初含まれていたパスワードはすべて失われます。

FormattingOptions 、toEncoded()、およびtoString()も参照してください 。

QByteArray QUrl::toEncoded(QUrl::FormattingOptions options = FullyEncoded) const

URLが有効な場合は、そのエンコードされた表現を返します。そうでない場合は、空のQByteArray が返されます。options でフラグを渡すことで、出力をカスタマイズできます。

ユーザー情報、パス、フラグメントはすべてUTF-8に変換され、非ASCII文字はすべてパーセントエンコードされます。ホスト名はPunycodeを使用してエンコードされます。

QString QUrl::toLocalFile() const

このURLのパスを、ローカルファイルパスとしてフォーマットして返します。返されるパスには、元のURLがバックスラッシュで構成されていた場合でも、スラッシュが使用されます。

このURLにホスト名が含まれている場合、SMBネットワークで用いられる形式（例: "//servername/path/to/file.txt"）でエンコードされて返されます。

qDebug()<<QUrl("file:file.txt").toLocalFile();            // "file.txt"
qDebug() << QUrl("file:/home/user/file.txt").toLocalFile(); // "/home/user/file.txt"
qDebug() << QUrl("file.txt").toLocalFile();                 // ""; wasn't a local file as it had no scheme

注：このURLのパス部分にUTF-8以外のバイナリシーケンス（%80など）が含まれている場合、この関数の動作は未定義となります。

fromLocalFile() およびisLocalFile()も参照してください 。

NSURL *QUrl::toNSURL() const

QUrl から NSURL を作成します。

NSURLはオートリリースされます。

[static] QByteArray QUrl::toPercentEncoding(const QString &input, const QByteArray &exclude = QByteArray(), const QByteArray &include = QByteArray())

input のエンコード済みコピーを返します。input はまずUTF-8に変換され、非予約グループに含まれないすべてのASCII文字はパーセントエンコードされます。文字がパーセントエンコードされないようにするには、それらをexclude に渡してください。文字を強制的にパーセントエンコードするには、それらをinclude に渡してください。

「非予約」は次のように定義されます：ALPHA / DIGIT / "-" / "." / "_" / "~"

QByteArray ba=QUrl::toPercentEncoding("{a fishy string?}", "{}", "s");
qDebug(ba.constData());
// 「{a fi%73hy %73tring%3F}」と出力する

QString QUrl::toString(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const

URL を文字列として返します。options を使用してフラグを渡すことで、出力をカスタマイズできます。QUrl::FullyDecoded オプションは、曖昧なデータを生成してしまうため、この関数では使用できません。

デフォルトの書式設定オプションは `PrettyDecoded` です。

FormattingOptions 、url()、およびsetUrl()も参照してください 。

[static] QStringList QUrl::toStringList(const QList<QUrl> &urls, QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded))

toString （options ）を使用して、urls のリストをQString オブジェクトのリストに変換します。

QString QUrl::url(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const

URLの文字列表現を返します。options でフラグを渡すことで、出力をカスタマイズできます。QUrl::FullyDecoded オプションは、曖昧なデータを生成してしまうため、この関数では使用できません。

結果として得られたQString は、後でQUrl に再度渡すことができます。

toString(options) の別名です。

setUrl()、FormattingOptions 、toEncoded()、およびtoString()も参照してください 。

QString QUrl::userInfo(QUrl::ComponentFormattingOptions options = PrettyDecoded) const

URL のユーザー情報を返します。ユーザー情報が未定義の場合は、空の文字列を返します。

この関数は、曖昧さのない値を返します。この値には、依然としてパーセントエンコードされた文字や、QString でデコードされた形式では表現できない一部の制御シーケンスが含まれる場合があります。

options 引数は、ユーザー情報コンポーネントのフォーマット方法を制御します。この関数では、QUrl::FullyDecoded の値は許可されていません。完全にデコードされたデータを取得する必要がある場合は、userName()とpassword()を個別に呼び出してください。

setUserInfo()、userName()、password()、およびauthority()も参照してください 。

QString QUrl::userName(QUrl::ComponentFormattingOptions options = FullyDecoded) const

URLにユーザー名が定義されている場合はそのユーザー名を返し、定義されていない場合は空の文字列を返します。

options 引数は、ユーザー名コンポーネントのフォーマット方法を制御します。どの値を設定しても、結果に曖昧さは生じません。QUrl::FullyDecoded を指定すると、すべてのパーセントエンコードされたシーケンスがデコードされます。それ以外の場合、QString でデコードされた形式では表現できない一部の制御シーケンスに対して、返される値にパーセントエンコードされたシーケンスが含まれる可能性があります。

なお、QUrl::FullyDecoded を使用すると、表現不可能なシーケンスが存在する場合にデータが失われる可能性があることに注意してください。この値は、QAuthenticator での設定やログインのネゴシエーションなど、URL以外のコンテキストで結果が使用される場合に使用することを推奨します。

setUserName() およびuserInfo()も参照してください 。

[noexcept] QUrl &QUrl::operator=(QUrl &&other)

other をこのQUrl インスタンスに割り当てます。

QUrl &QUrl::operator=(const QString &url)

指定されたurl をこのオブジェクトに割り当てます。

QT_NO_URL_CAST_FROM_STRING マクロが定義されている場合、この演算子は使用できません。

[noexcept] QUrl &QUrl::operator=(const QUrl &url)

指定されたurl をこのオブジェクトに割り当てます。