Fead/add dict args

README.md

@@ -117,7 +117,7 @@ ZSTD\_VERSION\_TEXT            | libzstd version string
 #### Description
 
 ``` php
-zstd_compress ( string $data, int $level = ZSTD_COMPRESS_LEVEL_DEFAULT ): string|false
+zstd_compress ( string $data, int $level = ZSTD_COMPRESS_LEVEL_DEFAULT, ?string $dict = null ): string|false
 ```
 
 Zstandard compression.
@@ -136,6 +136,10 @@ Zstandard compression.
   A value smaller than 0 means a faster compression level.
   (Zstandard library 1.3.4 or later)
 
+* _dict_
+
+  The Dictionary data.
+
 #### Return Values
 
 Returns the compressed data or FALSE if an error occurred.
@@ -146,7 +150,7 @@ Returns the compressed data or FALSE if an error occurred.
 #### Description
 
 ``` php
-zstd_uncompress ( string $data ): string|false
+zstd_uncompress ( string $data, ?string $dict = null ): string|false
 ```
 
 Zstandard decompression.
@@ -159,13 +163,19 @@ Zstandard decompression.
 
   The compressed string.
 
+* _dict_
+
+  The Dictionary data.
+
 #### Return Values
 
 Returns the decompressed data or FALSE if an error occurred.
 
 ---
 ### zstd\_compress\_dict — Zstandard compression using a digested dictionary
 
+> deprecated: use zstd\_compress() insted
+
 #### Description
 
 ``` php
@@ -198,6 +208,8 @@ Returns the compressed data or FALSE if an error occurred.
 ---
 ### zstd\_uncompress\_dict — Zstandard decompression using a digested dictionary
 
+> deprecated: use zstd\_uncompress() insted
+
 #### Description
 
 ``` php
@@ -229,7 +241,7 @@ Returns the decompressed data or FALSE if an error occurred.
 #### Description
 
 ``` php
-zstd_compress_init ( int $level = ZSTD_COMPRESS_LEVEL_DEFAULT ): Zstd\Compress\Context|false
+zstd_compress_init ( int $level = ZSTD_COMPRESS_LEVEL_DEFAULT, ?string $dict = null ): Zstd\Compress\Context|false
 ```
 
 Initialize an incremental compress context
@@ -241,6 +253,10 @@ Initialize an incremental compress context
   The higher the level, the slower the compression.
   (Defaults to `ZSTD_COMPRESS_LEVEL_DEFAULT`)
 
+* _dict_
+
+  The Dictionary data.
+
 #### Return Values
 
 Returns a zstd context instance on success, or FALSE on failure
@@ -280,11 +296,17 @@ Returns a chunk of compressed data, or FALSE on failure.
 #### Description
 
 ``` php
-zstd_uncompress_init ( void ): Zstd\UnCompress\Context|false
+zstd_uncompress_init ( ?string $dict = null ): Zstd\UnCompress\Context|false
 ```
 
 Initialize an incremental uncompress context
 
+#### Parameters
+
+* _dict_
+
+  The Dictionary data.
+
 #### Return Values
 
 Returns a zstd context instance on success, or FALSE on failure
@@ -370,6 +392,7 @@ readfile("compress.zstd:///path/to/data.zstd");
 $context = stream_context_create([
     'zstd' => [
             'level' => ZSTD_COMPRESS_LEVEL_MIN,
+            // 'dict' => $dict,
         ],
     ],
 );

tests/005.phpt

@@ -22,7 +22,7 @@ var_dump(zstd_uncompress($testclass));
 --EXPECTF--
 *** Testing zstd_uncompress() function with Zero arguments ***
 
-Warning: zstd_uncompress() expects exactly 1 parameter, 0 given in %s on line %d
+Warning: zstd_uncompress() expects at least 1 parameter, 0 given in %s on line %d
 bool(false)
 *** Testing with incorrect arguments ***
 

tests/005_b.phpt

@@ -33,7 +33,7 @@ try {
 ===DONE===
 --EXPECTF--
 *** Testing zstd_uncompress() function with Zero arguments ***
-ArgumentCountError: zstd_uncompress() expects exactly 1 argument, 0 given in %s:%d
+ArgumentCountError: zstd_uncompress() expects at least 1 argument, 0 given in %s:%d
 Stack trace:
 #0 %s(%d): zstd_uncompress()
 #1 {main}

tests/dictionary_01_b.phpt

@@ -0,0 +1,74 @@
+--TEST--
+zstd_compress(): use dict compress level
+--FILE--
+<?php
+include(dirname(__FILE__) . '/data.inc');
+$dictionary = file_get_contents(dirname(__FILE__) . '/data.dic');
+
+function check_compress($data, $dictionary, $level)
+{
+  $output = (string)zstd_compress($data, $level, $dictionary);
+  echo $level, ' -- ', strlen($dictionary), ' -- ', strlen($output), ' -- ',
+    var_export(zstd_uncompress($output, $dictionary) === $data, true), PHP_EOL;
+}
+
+echo "*** Data size ***", PHP_EOL;
+echo strlen($data), PHP_EOL;
+
+echo "*** Compression Level ***", PHP_EOL;
+for (
+  $level = ZSTD_COMPRESS_LEVEL_MIN;
+  $level <= ZSTD_COMPRESS_LEVEL_MAX;
+  $level++
+) {
+  check_compress($data, $dictionary, $level);
+}
+
+echo "*** Faster compression Level ***", PHP_EOL;
+for ($level = -1; $level >= -5; $level--) {
+  check_compress($data, $dictionary, $level);
+}
+
+echo "*** Invalid Compression Level ***", PHP_EOL;
+check_compress($data, $dictionary, 100);
+?>
+===Done===
+--EXPECTF--
+*** Data size ***
+3547
+*** Compression Level ***
+1 -- 142 -- 1%d -- true
+2 -- 142 -- 1%d -- true
+3 -- 142 -- 1%d -- true
+4 -- 142 -- 1%d -- true
+5 -- 142 -- 1%d -- true
+6 -- 142 -- 1%d -- true
+7 -- 142 -- 1%d -- true
+8 -- 142 -- 1%d -- true
+9 -- 142 -- 1%d -- true
+10 -- 142 -- 1%d -- true
+11 -- 142 -- 1%d -- true
+12 -- 142 -- 1%d -- true
+13 -- 142 -- 1%d -- true
+14 -- 142 -- 1%d -- true
+15 -- 142 -- 1%d -- true
+16 -- 142 -- 1%d -- true
+17 -- 142 -- 1%d -- true
+18 -- 142 -- 1%d -- true
+19 -- 142 -- 1%d -- true
+20 -- 142 -- 1%d -- true
+21 -- 142 -- 1%d -- true
+22 -- 142 -- 1%d -- true
+*** Faster compression Level ***
+-1 -- 142 -- %d -- true
+-2 -- 142 -- %d -- true
+-3 -- 142 -- %d -- true
+-4 -- 142 -- %d -- true
+-5 -- 142 -- %d -- true
+*** Invalid Compression Level ***
+
+Warning: zstd_compress(): compression level (100) must be within 1..22 or smaller then 0 in %s on line %d
+100 -- 142 -- 0 -- 
+Warning: zstd_uncompress(): it was not compressed by zstd in %s
+false
+===Done===

tests/dictionary_b.phpt

@@ -0,0 +1,28 @@
+--TEST--
+zstd_compress(): use dict
+--SKIPIF--
+--FILE--
+<?php
+include(dirname(__FILE__) . '/data.inc');
+$dictionary = file_get_contents(dirname(__FILE__) . '/data.dic');
+
+function check_compress_dict($data, $dictionary)
+{
+  $output = (string)zstd_compress($data, ZSTD_COMPRESS_LEVEL_DEFAULT, $dictionary);
+  echo strlen($dictionary), ' -- ', strlen($output), ' -- ',
+    var_export(zstd_uncompress($output, $dictionary) === $data, true), PHP_EOL;
+}
+
+echo "*** Data size ***", PHP_EOL;
+echo strlen($data), PHP_EOL;
+
+echo "*** Dictionary Compression ***", PHP_EOL;
+check_compress_dict($data, $dictionary);
+?>
+===Done===
+--EXPECTF--
+*** Data size ***
+3547
+*** Dictionary Compression ***
+142 -- 1%d -- true
+===Done===

tests/inc_dictionary.phpt

@@ -0,0 +1,68 @@
+--TEST--
+Incremental dictionary compression
+--FILE--
+<?php
+include(dirname(__FILE__) . '/data.inc');
+$dictionary = file_get_contents(dirname(__FILE__) . '/data.dic');
+
+foreach ([128, 512, 1024] as $size) {
+  var_dump($size);
+  $handle = zstd_compress_init(ZSTD_COMPRESS_LEVEL_DEFAULT, $dictionary);
+  var_dump($handle);
+
+  $pos= 0;
+  $compressed = '';
+  while ($pos < strlen($data)) {
+    $chunk = substr($data, $pos, $size);
+    $compressed .= zstd_compress_add($handle, $chunk, false);
+    $pos += strlen($chunk);
+  }
+  $compressed .= zstd_compress_add($handle, '', true);
+  var_dump(strlen($compressed), strlen($compressed) < strlen($data));
+
+  var_dump($data === zstd_uncompress($compressed, $dictionary));
+
+  $handle = zstd_uncompress_init($dictionary);
+  var_dump($handle);
+
+  $pos= 0;
+  $uncompressed = '';
+  while ($pos < strlen($compressed)) {
+    $chunk = substr($compressed, $pos, $size);
+    $uncompressed .= zstd_uncompress_add($handle, $chunk);
+    $pos += strlen($chunk);
+  }
+
+  var_dump($data === $uncompressed);
+}
+?>
+===Done===
+--EXPECTF--
+int(128)
+object(Zstd\Compress\Context)#%d (0) {
+}
+int(%d)
+bool(true)
+bool(true)
+object(Zstd\UnCompress\Context)#%d (0) {
+}
+bool(true)
+int(512)
+object(Zstd\Compress\Context)#%d (0) {
+}
+int(%d)
+bool(true)
+bool(true)
+object(Zstd\UnCompress\Context)#%d (0) {
+}
+bool(true)
+int(1024)
+object(Zstd\Compress\Context)#%d (0) {
+}
+int(%d)
+bool(true)
+bool(true)
+object(Zstd\UnCompress\Context)#%d (0) {
+}
+bool(true)
+===Done===

tests/inc_named_args.phpt

@@ -7,13 +7,14 @@ if (PHP_VERSION_ID < 80000) die("skip requires PHP 8.0+");
 --FILE--
 <?php
 include(dirname(__FILE__) . '/data.inc');
+$dictionary = file_get_contents(dirname(__FILE__) . '/data.dic');
 
-function test($data, $level = 0) {
-    echo "level={$level}\n";
+function test($data, $dict, $level = 0) {
+    echo "level={$level},dict=", gettype($dict), "\n";
 
     $compressed = '';
 
-    $context = zstd_compress_init(level: $level);
+    $context = zstd_compress_init(level: $level, dict: $dict);
     if ($context === false) {
         echo "ERROR\n";
         return;
@@ -31,14 +32,14 @@ function test($data, $level = 0) {
         end: true,
     );
 
-    if ($data === zstd_uncompress(data: $compressed)) {
+    if ($data === zstd_uncompress(data: $compressed, dict: $dict)) {
         echo "OK\n";
     } else {
         echo "ERROR: uncompress\n";
     }
 
     $out = '';
-    $context = zstd_uncompress_init();
+    $context = zstd_uncompress_init(dict: $dict);
     foreach (str_split($compressed, 6) as $var) {
         $out .= zstd_uncompress_add(
             context: $context,
@@ -53,25 +54,42 @@ function test($data, $level = 0) {
 }
 
 foreach ([0, 9, 22, 30, -1] as $level) {
-    test($data, $level, 0);
+    test($data, null, $level);
+    test($data, $dictionary, $level);
 }
 ?>
 ===DONE===
 --EXPECTF--
-level=0
+level=0,dict=NULL
 OK
 Ok
-level=9
+level=0,dict=string
 OK
 Ok
-level=22
+level=9,dict=NULL
 OK
 Ok
-level=30
+level=9,dict=string
+OK
+Ok
+level=22,dict=NULL
+OK
+Ok
+level=22,dict=string
+OK
+Ok
+level=30,dict=NULL
 
 Warning: zstd_compress_init(): compression level (30) must be within 1..22 or smaller then 0 in %s on line %d
 ERROR
-level=-1
+level=30,dict=string
+
+Warning: zstd_compress_init(): compression level (30) must be within 1..22 or smaller then 0 in %s on line %d
+ERROR
+level=-1,dict=NULL
+OK
+Ok
+level=-1,dict=string
 OK
 Ok
 ===DONE===