URLCompressorライブラリ(3)

このページをスマートフォンなどでご覧になる場合は、画面を横長にする方が読みやすくなる事があります。

7.URLCompressorの使い方

7-1.URLCompressorライブラリの読み込み方

URLCompressorライブラリを使うには、url-comp.jsを読み込む必要があります。

7-1-1.WEBページのクライアントサイドで使う場合

WEBページのクライアントサイド(ブラウザ上)でURLCompressorライブラリを使うには、例えば、HTMLのHEAD要素内で

などと記述します。(上の例では、url-comp.jsをHTMLファイルと同じディレクトリに置いています)

7-1-2.Node.jsで使う場合

Node.jsでURLCompressorライブラリを使うには、プロジェクトと同じフォルダにurl-comp.jsを置き、使う側のJavaScriptのファイルで、

注:筆者は、Node.jsの事を良く分かっていません。問題がありましたら、Twitterかメールで連絡いただけるとありがたいです。

7-2.URLCompressorライブラリの関数

URLCompressorライブラリの内部では、URLCompressorというオブジェクト変数を定義しています。(ライブラリと同名の変数)

このURLCompressorオブジェクトには、次の4つのメソッド(関数)があります。

これら4つの関数の内、圧縮(エンコード)と伸長(デコード)に使うのはURLCompressor.compress関数と、URLCompressor.expand関数の2つです。

URLCompressor.encodeUtf8関数とURLCompressor.decodeUtf8関数の2つは、URLCompressorライブラリ内部で使用している関数なのですが、汎用性があるので、外部からも利用できる様にしています。

7-3.圧縮(エンコード)の方法

文字列を圧縮(エンコード)するには、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形式で圧縮するサンプルコードを示します。

リスト4、URLCompressor.compress関数を使って文字列を圧縮するサンプルコードCOPY

const originalStr='本日は晴天なり。';
const encodedStr=URLCompressor.compress(originalStr);
console.log(encodedStr);
// expected result: 'DiX8ReaZzrfpP4jxuH4JVY0ne47QHoZ'

リスト4をpaizaIOで実行した結果を次に示します。変数originalStrを書き換えると、色々な文字列が圧縮できます。

7-4.伸長(デコード)の方法

URLCompresor.compress関数で圧縮した文字列を伸長(デコード)するには、URLCompressor.expand関数を使います。

URLCompressor.expand関数には、strとdecode64の2つの引数があります。

第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"("本日は晴天なり。"を圧縮して得られた文字列)を伸長するサンプルコードを示します。

リスト5、URLCompressor.expand関数を使って文字列を伸長するサンプルコードCOPY

const encodedStr='DiX8ReaZzrfpP4jxuH4JVY0ne47QHoZ';
const originalStr=URLCompressor.expand(encodedStr);
console.log(originalStr);
// expected result: '本日は晴天なり。'

リスト5をpaizaIOで実行した結果を次に示します。変数encodedStrを書き換えると、色々な文字列が伸長できます。

参考:変数encodedStrに不正な文字列(例えば"!!!")を入力すると、URLCompressor.expand関数がnull("null"という文字列ではない)を返す事が確かめられます。

7-5.URLCompresor.encodeUtf8関数の使い方

URLCompressor.encodeUtf8関数は、UTF-16表現された、標準的なJavaScriptの文字列を、UTF-8表現の文字列に変換します。

JavaScript標準のTextEncoder.prototype.encode関数でも、UTF-16からUTF-8への変換ができますが、TextEncoder.prototype.encode関数では、UTF-8に変換された文字列が、Uint8Arrayで返って来るのに対し、URLCompressor.encodeUtf8関数では文字列で返ってくる点が違います。

返り値は、UTF-8表現された文字列(文字コードは0～255の範囲)です。

ただし、UTF-16からUTF-8への変換の最中にエラーが発生した場合は、nullを返します。(エラーになっても例外は発生しません)

7-6.URLCompressor.decodeUtf8関数の使い方

URLCompressor.decodeUtf8関数は、URLCompressor.encodeUtf8関数で生成されたUTF-8表現の文字列を、Javascript標準のUTF-16表現の文字列に変換します。

JavaScript標準のTextDecoder.prototype.decode関数でも、UTF-8からUTF-16への変換ができますが、TextEncode.prototype.decode関数では、ArrayBufferやArrayBufferViewを引数に取るのに対し、URLCompressor.decodeUtf8関数では文字列を引数に取る点が違います。

ただし、UTF-8からUTF-8の変換の最中にエラーが発生した場合は、nullを返します。(エラーになっても例外は発生しません)