From 1a0b4ddf340130d270a4c96a36f915eb5b0399f3 Mon Sep 17 00:00:00 2001
From: "Michael Hirsch, Ph.D" <scivision@users.noreply.github.com>
Date: Sun, 10 Nov 2019 22:49:39 -0500
Subject: fs: further document and test behavior

---
 docs/markdown/Fs-module.md                  | 30 ++++++++++++++++++++++++++---
 test cases/common/227 fs module/meson.build | 12 ++++++++++++
 2 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/docs/markdown/Fs-module.md b/docs/markdown/Fs-module.md
index 3332b1e..7c2925f 100644
--- a/docs/markdown/Fs-module.md
+++ b/docs/markdown/Fs-module.md
@@ -36,11 +36,35 @@ by the string is a symbolic link.
 
 ### with_suffix
 
-The `with_suffix` method allows changing the filename suffix
+The `with_suffix` method is a *string manipulation* convenient for filename modifications.
+It allows changing the filename suffix like:
+
+## swap suffix
 
 ```meson
 original = '/opt/foo.ini'
-new = fs.with_suffix('.txt')
+new = fs.with_suffix('.txt')  # /opt/foo.txt
+```
+
+#### add suffix
+
+```meson
+original = '/opt/foo'
+new = fs.with_suffix('.txt')  # /opt/foo.txt
+```
+
+#### compound suffix swap
+
+```meson
+original = '/opt/foo.dll.a'
+new = fs.with_suffix('.so')  # /opt/foo.dll.so
+```
+
+#### delete suffix
+
+```meson
+original = '/opt/foo.dll.a'
+new = fs.with_suffix('')  # /opt/foo.dll
 ```
 
-The files need not actually exist yet for this method.
\ No newline at end of file
+The files need not actually exist yet for this method, as it's just string manipulation.
\ No newline at end of file
diff --git a/test cases/common/227 fs module/meson.build b/test cases/common/227 fs module/meson.build
index 75f4a99..f111d46 100644
--- a/test cases/common/227 fs module/meson.build	
+++ b/test cases/common/227 fs module/meson.build	
@@ -27,6 +27,18 @@ original = 'foo.txt'
 new = fs.with_suffix(original, '.ini')
 assert(new.endswith('foo.ini') and not new.contains('.txt'), 'with_suffix failed')
 
+original = 'foo'
+new = fs.with_suffix(original, '.ini')
+assert(new.endswith('foo.ini'), 'with_suffix did not add suffix to suffixless file')
+
+original = 'foo.dll.a'
+new = fs.with_suffix(original, '.so')
+assert(new.endswith('foo.dll.so'), 'with_suffix did not only modify last suffix')
+
+original = 'foo.dll'
+new = fs.with_suffix(original, '')
+assert(new.endswith('foo'), 'with_suffix did not only delete last suffix')
+
 # `/` on windows is interpreted like `.drive` which in general may not be `c:/`
 # the files need not exist for fs.with_suffix()
 original = is_windows ? 'j:/foo/bar.txt' : '/foo/bar.txt'
-- 
cgit v1.1