| 2021年06月28日 | 公開。 |
この章では、URLCompressorの使い方を説明します。
URLCompressorライブラリを使うには、url-comp.jsを読み込む必要があります。
WEBページのクライアントサイド(ブラウザ上)でURLCompressorライブラリを使うには、例えば、HTMLのHEAD要素内で
などと記述します。(上の例では、url-comp.jsをHTMLファイルと同じディレクトリに置いています)
Node.jsでURLCompressorライブラリを使うには、プロジェクトと同じフォルダにurl-comp.jsを置き、使う側のJavaScriptのファイルで、
と記述します。
注:筆者は、Node.jsの事を良く分かっていません。問題がありましたら、Twitterかメールで連絡いただけるとありがたいです。
URLCompressorライブラリの内部では、URLCompressorというオブジェクト変数を定義しています。(ライブラリと同名の変数)
このURLCompressorオブジェクトには、次の4つのメソッド(関数)があります。
これら4つの関数の内、圧縮(エンコード)と伸長(デコード)に使うのはURLCompressor.compress関数と、URLCompressor.expand関数の2つです。
URLCompressor.encodeUtf8関数とURLCompressor.decodeUtf8関数の2つは、URLCompressorライブラリ内部で使用している関数なのですが、汎用性があるので、外部からも利用できる様にしています。
文字列を圧縮(エンコード)するには、URLCompressor.compress関数を使います。
URLCompressor.compress関数の書式を次に示します。
URLCompressor.compress関数には、strとencode64の2つの引数があります。
第1引数のstrには、圧縮したい文字列を渡します。文字列はUTF-16表現として正しい物である必要があります。前半サロゲートの後に後半サロゲートがない、不正なUTF-16表現の文字列は圧縮できません。
第2引数のencode64は、圧縮結果をBase 64 URL形式の文字列にするかどうかを示す論理型(trueまたはfalse)の引数です。
encode64がtrueなら、圧縮結果をBase 64 URL形式の文字列(英数字と-と_の、URLとして使える64文字のみからなる文字列)で返します。
encode64がfalseなら、圧縮結果をバイナリ文字列(文字コードが0～255の範囲の文字からなる文字列)で返します。
encode64の指定を省略すると、trueを指定したものとして解釈されます。
URLCompressor.compress関数の返り値は、圧縮済みの文字列になります。
ただし、圧縮処理でエラーが発生した場合は、返り値がnullになります。(エラーになっても例外は発生しません)
リスト4に、URLCompressor.compress関数で"本日は晴天なり。"をBase 64 URL形式で圧縮するサンプルコードを示します。
const originalStr='本日は晴天なり。';
const encodedStr=URLCompressor.compress(originalStr);
console.log(encodedStr);
// expected result: 'DiX8ReaZzrfpP4jxuH4JVY0ne47QHoZ'
リスト4をpaizaIOで実行した結果を次に示します。変数originalStrを書き換えると、色々な文字列が圧縮できます。
URLCompresor.compress関数で圧縮した文字列を伸長(デコード)するには、URLCompressor.expand関数を使います。
URLCompressor.expand関数の書式を次に示します。
URLCompressor.expand関数には、strとdecode64の2つの引数があります。
第1引数のstrには、伸長したい文字列を渡します。
第2引数のdecode64は、strとして渡した文字列が、Base 64 URL形式の文字列であるのかどうかを示す、論理型(trueまたはfalse)の引数です。
decode64がtrueなら、strはBase 64 URL形式の文字列であるとみなして伸長します。
decode64がfalseなら、strはバイナリ文字列であるとみなして伸長します。
decode64の指定を省略すると、trueを指定したものとして解釈されます。
圧縮時にURLCompressor.compress関数の第2引数(encode64)に指定したのと同じ真理値を、URLCompressor.expand関数の第2引数(decode64)に指定する必要があります。
URLCompressor.expand関数の返り値は、伸長済みの文字列になります。
ただし、伸長処理でエラーが発生した場合は、返り値がnullになります。(エラーになっても例外は発生しません)
リスト5に、"DiX8ReaZzrfpP4jxuH4JVY0ne47QHoZ"("本日は晴天なり。"を圧縮して得られた文字列)を伸長するサンプルコードを示します。
const encodedStr='DiX8ReaZzrfpP4jxuH4JVY0ne47QHoZ';
const originalStr=URLCompressor.expand(encodedStr);
console.log(originalStr);
// expected result: '本日は晴天なり。'
リスト5をpaizaIOで実行した結果を次に示します。変数encodedStrを書き換えると、色々な文字列が伸長できます。
参考:変数encodedStrに不正な文字列(例えば"!!!")を入力すると、URLCompressor.expand関数がnull("null"という文字列ではない)を返す事が確かめられます。
URLCompressor.encodeUtf8関数は、UTF-16表現された、標準的なJavaScriptの文字列を、UTF-8表現の文字列に変換します。
JavaScript標準のTextEncoder.prototype.encode関数でも、UTF-16からUTF-8への変換ができますが、TextEncoder.prototype.encode関数では、UTF-8に変換された文字列が、Uint8Arrayで返って来るのに対し、URLCompressor.encodeUtf8関数では文字列で返ってくる点が違います。
URLCompressor.encodeUtf8関数の書式を次に示します。
引数のstrにはUTF-16表現の文字列を渡します。
返り値は、UTF-8表現された文字列(文字コードは0～255の範囲)です。
ただし、UTF-16からUTF-8への変換の最中にエラーが発生した場合は、nullを返します。(エラーになっても例外は発生しません)
URLCompressor.decodeUtf8関数は、URLCompressor.encodeUtf8関数で生成されたUTF-8表現の文字列を、Javascript標準のUTF-16表現の文字列に変換します。
JavaScript標準のTextDecoder.prototype.decode関数でも、UTF-8からUTF-16への変換ができますが、TextEncode.prototype.decode関数では、ArrayBufferやArrayBufferViewを引数に取るのに対し、URLCompressor.decodeUtf8関数では文字列を引数に取る点が違います。
URLCompressor.decodeUtf8関数の書式を次に示します。
引数のstrには、UTF-8表現の文字列を渡します。
返り値は、UTF-16表現されたJavaScriptの標準的な文字列です。
ただし、UTF-8からUTF-8の変換の最中にエラーが発生した場合は、nullを返します。(エラーになっても例外は発生しません)
