Mô đun:String/tài liệu

Mô đun:String (sửa | thảo luận | lịch sử | liên kết | theo dõi | nhật trình)

Mô đun này nhằm cung cấp quyền truy cập vào các hàm xử lý chuỗi cơ bản.

Hầu hết các hàm được cung cấp ở đây có thể được gọi bằng tham số có tên, tham số không tên hoặc kết hợp cả hai. Nếu sử dụng tham số có tên, Mediawiki sẽ tự động loại bỏ mọi khoảng trắng ở đầu hoặc cuối tham số. Tùy thuộc vào mục đích sử dụng, có thể có lợi khi giữ lại hoặc loại bỏ các khoảng trắng đó.

Các tùy chọn toàn cục

ignore_errors

Nếu đặt là 'true' hoặc 1, bất kỳ điều kiện lỗi nào sẽ trả về một chuỗi rỗng thay vì thông báo lỗi.

error_category

Nếu xảy ra lỗi, chỉ định tên của thể loại để đưa vào thông báo lỗi. Thể loại mặc định là Thể loại:Trang gây lỗi trong mô đun String (0).

no_category

Nếu đặt là 'true' hoặc 1, sẽ không có thể loại nào được thêm vào nếu xảy ra lỗi.

Các kiểm thử đơn vị cho mô đun này có tại Module:String/testcases.

len

Hàm này trả về độ dài của chuỗi mục tiêu.

Cách dùng:

{{#invoke:String|len|chuỗi_mục_tiêu}}

HOẶC

{{#invoke:String|len|s= chuỗi_mục_tiêu }}

Các tham số:

s

Chuỗi cần lấy độ dài

Ví dụ:

• {{#invoke:String|len| abcdefghi }} → 11
• {{#invoke:String|len|s= abcdefghi }} → 9

sub

Hàm này trả về một chuỗi con của chuỗi mục tiêu tại các chỉ mục được chỉ định (bao gồm cả chỉ mục đó), đánh số bắt đầu từ 1.

Cách dùng:

{{#invoke:String|sub|chuỗi_mục_tiêu|chỉ_mục_đầu|chỉ_mục_cuối}}

HOẶC

{{#invoke:String|sub|s= chuỗi_mục_tiêu |i= chỉ_mục_đầu |j= chỉ_mục_cuối }}

Các tham số:

s

Chuỗi cần lấy tập con

i

Chỉ mục đầu tiên của chuỗi con cần lấy, mặc định là 1.

j

Chỉ mục cuối cùng của chuỗi con cần lấy, mặc định là ký tự cuối cùng.

Ký tự đầu tiên của chuỗi được gán chỉ mục là 1. Nếu i hoặc j là giá trị âm, nó được hiểu là chọn ký tự bằng cách đếm ngược từ cuối chuỗi. Do đó, giá trị -1 tương đương với việc chọn ký tự cuối cùng của chuỗi.

Nếu các chỉ mục yêu cầu nằm ngoài phạm vi của chuỗi đã cho, lỗi sẽ được báo cáo. Để tránh thông báo lỗi, hãy sử dụng {{#gọi:ustring|sub}} thay thế.

Ví dụ:

• "{{#invoke:String|sub| abcdefghi }}" → " abcdefghi "
• "{{#invoke:String|sub|s= abcdefghi }}" → "abcdefghi"
• "{{#invoke:String|sub| abcdefghi | 3 }}" → "bcdefghi "
• "{{#invoke:String|sub|s= abcdefghi |i= 3 }}" → "cdefghi"
• "{{#invoke:String|sub| abcdefghi | 3 | 4 }}" → "bc"
• "{{#invoke:String|sub|s= abcdefghi |i= 3 |j= 4 }}" → "cd"

sublength

Hàm này thực hiện các tính năng của {{str sub old}} và được giữ lại để duy trì các bản mẫu cũ này. Nó trả về một chuỗi con của chuỗi mục tiêu bắt đầu từ một chỉ mục được chỉ định và có độ dài nhất định.

Cách dùng:

{{#invoke:String|sublength|s= chuỗi_mục_tiêu |i= chỉ_mục_đầu |len= độ_dài }}

Các tham số:

s

Chuỗi nguồn

i

Chỉ mục bắt đầu của chuỗi con cần trả về. Ký tự đầu tiên của chuỗi được gán chỉ mục là 0.

len

Độ dài của chuỗi cần trả về, mặc định là đến ký tự cuối cùng.

Ví dụ:

• {{#invoke:String|sublength|s= abcdefghi }} → abcdefghi
• {{#invoke:String|sublength|s= abcdefghi |i= 3 }} → defghi
• {{#invoke:String|sublength|s= abcdefghi |i= 3 |len= 4 }} → defg

match

Hàm này trả về một chuỗi con từ chuỗi nguồn khớp với một mẫu (pattern) được chỉ định.

Cách dùng:

{{#invoke:String|match|chuỗi_nguồn|chuỗi_mẫu|chỉ_mục_đầu|số_thứ_tự_khớp|cờ_plain|đầu_ra_khi_không_khớp}}

HOẶC

{{#invoke:String|match|s= chuỗi_nguồn |pattern= chuỗi_mẫu |start= chỉ_mục_đầu |match= số_thứ_tự_khớp |plain= cờ_plain |nomatch= đầu_ra_khi_không_khớp }}

Các tham số:

s

Chuỗi để tìm kiếm

pattern

Mẫu hoặc chuỗi cần tìm trong chuỗi nguồn

start

Chỉ mục trong chuỗi nguồn để bắt đầu tìm kiếm. Ký tự đầu tiên của chuỗi có chỉ mục là 1. Mặc định là 1.

match

Trong một số trường hợp, có thể có nhiều kết quả khớp trên một chuỗi duy nhất. Tham số này chỉ định kết quả khớp nào sẽ được trả về, trong đó kết quả đầu tiên là match= 1. Nếu chỉ định số âm, kết quả khớp sẽ được đếm ngược từ kết quả cuối cùng. Do đó match = -1 tương đương với yêu cầu kết quả khớp cuối cùng. Mặc định là 1.

plain

Cờ boolean chỉ ra rằng mẫu nên được hiểu là văn bản thuần túy và không phải là mẫu Scribunto ustring (một dạng biểu thức chính quy kiểu Lua thân thiện với unicode). Mặc định là false (để thay đổi: plain=true)

nomatch

Nếu không tìm thấy kết quả khớp, xuất ra giá trị "nomatch" thay vì lỗi.

ignore_errors

Nếu không tìm thấy kết quả khớp và ignore_errors=true, xuất ra chuỗi rỗng thay vì lỗi.

Nếu match_number hoặc start_index nằm ngoài phạm vi của chuỗi đang truy vấn, hàm này sẽ tạo ra lỗi. Lỗi cũng được tạo ra nếu không tìm thấy kết quả khớp.Nếu thêm tham số ignore_errors=true, lỗi sẽ bị chặn và chuỗi rỗng sẽ được trả về khi có bất kỳ thất bại nào.

Để biết thông tin về cách xây dựng mẫu Lua, một dạng của biểu thức chính quy, xem:

• Các mẫu Scribunto
• Các mẫu chuỗi Unicode Scribunto

Ví dụ:

• {{#invoke:String|match| abc123def456 |%d+}} → 123
• {{#invoke:String|match|s= abc123def456 |pattern= %d+ }} → 123
• {{#invoke:String|match| abc123def456 |%d+|6}} → 23
• {{#invoke:String|match|s= abc123def456 |pattern= %d+ |start= 6 }} → 3
• {{#invoke:String|match|s= abc123def456 |pattern= %d+ |start= 6 |match= 2 }} → 456
• {{#invoke:String|match|s= abc123%d+ |pattern= %d+ }} → 123
• {{#invoke:String|match|s= abc123%d+ |pattern= %d+ |plain= true }} → %d+
• {{#invoke:String|match|s= abc |pattern= %d }} →
• {{#invoke:String|match|s= abc |pattern= %d |nomatch= Không có ký tự số trong chuỗi }} → Không có ký tự số trong chuỗi
• {{#invoke:String|match|s= abc |pattern= %d |ignore_errors= true }} →
• {{#invoke:String|match|s= 0012001200 |pattern= 0*(%d*) }} → 12001200

pos

Hàm này trả về một ký tự đơn từ chuỗi mục tiêu tại vị trí pos.

Cách dùng:

{{#invoke:String|pos|chuỗi_mục_tiêu|giá_trị_chỉ_mục}}

HOẶC

{{#invoke:String|pos|target= chuỗi_mục_tiêu |pos= giá_trị_chỉ_mục }}

Các tham số:

target

Chuỗi cần tìm kiếm

pos

Chỉ mục của ký tự cần trả về

Ký tự đầu tiên có giá trị chỉ mục là 1.

Nếu yêu cầu một giá trị âm, hàm này sẽ chọn ký tự bằng cách đếm ngược từ cuối chuỗi. Nói cách khác pos = -1 tương đương với việc yêu cầu ký tự cuối cùng.

Giá trị yêu cầu bằng 0, hoặc lớn hơn độ dài của chuỗi sẽ trả về lỗi.

Ví dụ:

• {{#invoke:String|pos| abcdefghi | 4 }} → c
• {{#invoke:String|pos|target= abcdefghi |pos= 4 }} → d

str_find

Hàm này sao chép hành vi của {{str_find}}, bao gồm tất cả các đặc điểm kỳ quặc của nó. Hàm này được cung cấp để hỗ trợ các bản mẫu hiện có, nhưng KHÔNG ĐƯỢC KHUYẾN KHÍCH cho mã và bản mẫu mới. Mã mới được khuyến nghị sử dụng hàm "find" để thay thế.

Trả về chỉ mục đầu tiên trong "source" khớp với "target". Việc đánh chỉ mục bắt đầu từ 1, và hàm trả về -1 nếu chuỗi "target" không hiện diện trong "source".

Lưu ý quan trọng: Nếu chuỗi "target" trống / thiếu, hàm này trả về giá trị "1", đây là hành vi thường không mong muốn, và phải được tính toán riêng biệt.

Cách dùng:

{{#invoke:String|str_find|chuỗi_nguồn|chuỗi_mục_tiêu}}

HOẶC

{{#invoke:String|str_find|source= chuỗi_nguồn |target= chuỗi_mục_tiêu }}

Các tham số:

source

Chuỗi để tìm kiếm

target

Chuỗi cần tìm trong nguồn

Ví dụ:

• {{#invoke:String|str_find| abc123def }} → 1
• {{#invoke:String|str_find|source= abc123def }} → 1
• {{#invoke:String|str_find| abc123def |123}} → 5
• {{#invoke:String|str_find|source= abc123def |target= 123 }} → 4
• {{#invoke:String|str_find| abc123def |not}} → -1

find

Hàm này cho phép tìm kiếm một chuỗi mục tiêu hoặc mẫu trong một chuỗi khác.

Cách dùng:

{{#invoke:String|find|chuỗi_nguồn|chuỗi_mục_tiêu|chỉ_mục_đầu|cờ_plain}}

HOẶC

{{#invoke:String|find|source= chuỗi_nguồn |target= chuỗi_mục_tiêu |start= chỉ_mục_đầu |plain= cờ_plain }}

Các tham số:

source

Chuỗi để tìm kiếm

target

Chuỗi hoặc mẫu cần tìm trong nguồn

start

Chỉ mục trong chuỗi nguồn để bắt đầu tìm kiếm, mặc định là 1

plain

Cờ boolean chỉ ra rằng target nên được hiểu là văn bản thuần túy và không phải là mẫu Scribunto ustring (một dạng biểu thức chính quy kiểu Lua thân thiện với unicode); mặc định là true

Hàm này trả về chỉ mục đầu tiên >= "start" nơi tìm thấy "target" trong "source". Các chỉ mục bắt đầu từ 1. Nếu không tìm thấy "target", hàm trả về 0. Nếu "source" hoặc "target" bị thiếu / trống, hàm này cũng trả về 0.

Hàm này an toàn cho các chuỗi UTF-8.

Ví dụ:

• {{#invoke:String|find|abc123def|12}} → 4
• {{#invoke:String|find|source=abc123def|target=12}} → 4
• {{#invoke:String|find|source=abc123def|target=pqr}} → 0
• {{#invoke:String|find| abc123def |123}} → 5
• {{#invoke:String|find|source= abc123def |target= 123 }} → 4
• {{#invoke:String|find|source=abc123def|target=%d |start=3 |plain=false }} → 4

Khi sử dụng tham số không tên, khoảng trắng ở đầu và cuối được giữ lại và tính vào:

• {{#invoke:String|find| abc123def |c|false}} → 5
• {{#invoke:String|find|source= abc123def |target=c|plain=false}} → 3
• {{#invoke:string|find|abc 123 def|%s|plain=false}} → 4

Kiểm tra sự hiện diện của một chuỗi:

• {{#ifexpr:{{#invoke:string|find|haystack|needle}}|Found needle|Didn't find needle}} → Didn't find needle

findpagetext

Hàm findpagetext trả về vị trí của một đoạn văn bản trong mã nguồn wikitext của một trang. Nó nhận tối đa bốn tham số:

• Tham số vị trí đầu tiên hoặc |text là văn bản cần tìm kiếm.
• Tham số tùy chọn |title là tiêu đề trang, mặc định là trang hiện tại.
• Tham số tùy chọn |plain là true cho tìm kiếm thuần (mặc định), hoặc false cho tìm kiếm mẫu Lua.
• Tham số tùy chọn |nomatch là giá trị trả về khi không tìm thấy kết quả khớp; mặc định là không có gì.

Ví dụ

{{#invoke:String |findpagetext |text=Youghiogheny}} → 13612

{{#invoke:String |findpagetext |text=Youghiogheny |nomatch=không tìm thấy}} → 13612

{{#invoke:String |findpagetext |text=Youghiogheny |title=Cầu Boston |nomatch=không tìm thấy}} →

{{#invoke:String |findpagetext |text=sông |title=Cầu Boston |nomatch=không tìm thấy}} →

{{#invoke:String |findpagetext |text=[Ss]ông |title=Cầu Boston |plain=false |nomatch=không tìm thấy}} →

{{#invoke:String |findpagetext |text=%[%[ |title=Cầu Boston |plain=f |nomatch=không tìm thấy}} →

{{#invoke:String |findpagetext |text=%{%{[Cc]oord |title=Cầu Boston |plain=f |nomatch=không tìm thấy}} →

Việc tìm kiếm có phân biệt chữ hoa chữ thường, do đó cần khớp mẫu Lua để tìm sông hoặc Sông. Ví dụ cuối cùng tìm {{coord và {{Coord. Ví dụ áp chót tìm một liên kết wiki.

Bản mẫu:Findpagetext là một trình bao bọc tiện lợi cho hàm này.

replace (gsub)

Hàm này cho phép thay thế một chuỗi mục tiêu hoặc mẫu trong một chuỗi khác. Đối với các lập trình viên Lua: hàm này hoạt động nội bộ bằng cách gọi mw.ustring.gsub.

Cách dùng:

{{#invoke:String|replace|chuỗi_nguồn|chuỗi_mẫu|chuỗi_thay_thế|số_lượng_thay_thế|cờ_plain}}

HOẶC

{{#invoke:String|replace|source= chuỗi_nguồn |pattern= chuỗi_mẫu |replace= chuỗi_thay_thế |count= số_lượng_thay_thế |plain= cờ_plain }}

Các tham số:

source

Chuỗi để tìm kiếm

pattern

Chuỗi hoặc mẫu cần tìm trong nguồn

replace

Văn bản thay thế

count

Số lần xuất hiện cần thay thế; mặc định là tất cả

plain

Cờ boolean chỉ ra rằng mẫu nên được hiểu là văn bản thuần túy và không phải là mẫu Scribunto ustring (một dạng biểu thức chính quy kiểu Lua thân thiện với unicode); mặc định là true

Ví dụ:

• "{{#invoke:String|replace| abc123def456 |123|XYZ}}" → " abcXYZdef456 "
• "{{#invoke:String|replace|source= abc123def456 |pattern= 123 |replace= XYZ }}" → "abcXYZdef456"
• "{{#invoke:String|replace| abc123def456 |%d+|XYZ|1|false}}" → " abcXYZdef456 "
• "{{#invoke:String|replace|source= abc123def456 |pattern= %d+ |replace= XYZ |count=1 |plain= false }}" → "abcXYZdef456"
• "{{#invoke:String|replace|source= abc123def456 |pattern= %d+ |replace= XYZ |plain= false }}" → "abcXYZdefXYZ"
• {{#invoke:String|replace|source= 0012001200 |pattern= ^0* |plain= false }} → 12001200

rep

Lặp lại một chuỗi n lần. Một hàm đơn giản để chuyển string.rep vào các bản mẫu.

Cách dùng:

{{#invoke:String|rep|nguồn|số_lượng}}

Các tham số:

source

Chuỗi cần lặp lại

count

Số lần lặp lại.

Ví dụ:

• "{{#invoke:String|rep|hello|3}}" → "hellohellohello"
• "{{#invoke:String|rep| hello | 3 }}" → " hello hello hello "

escapePattern

Trong một mẫu Lua, thay đổi một ký tự lớp thành một ký tự nghĩa đen (literal). Ví dụ: trong một mẫu, ký tự . bắt "bất kỳ ký tự nào"; escapePattern sẽ chuyển đổi nó thành %., chỉ bắt ký tự chấm "." theo nghĩa đen.

Cách dùng:

• {{#invoke:String|escapePattern|chuỗi_mẫu}}

Các tham số:

pattern_string

Chuỗi mẫu cần thoát (escape)

Ví dụ:

• "{{#invoke:String|escapePattern|A.D.}}" → "A%.D%."
• "{{#invoke:String|escapePattern|10%}}" → "10%%"

count

Đếm số lần một mẫu nhất định xuất hiện trong các đối số được truyền cho mô đun này. Chỉ đếm các kết quả khớp rời rạc.

Cách dùng:

{{#invoke:String|count|chuỗi_nguồn|chuỗi_mẫu|cờ_plain}}

HOẶC

{{#invoke:String|count|source= chuỗi_nguồn |pattern= chuỗi_mẫu|plain= cờ_plain }}

Các tham số:

source_string

Chuỗi để đếm số lần xuất hiện trong đó

pattern

Chuỗi hoặc mẫu để đếm số lần xuất hiện trong nguồn

plain

Cờ boolean chỉ ra rằng mẫu nên được hiểu là văn bản thuần túy và không phải là mẫu Scribunto ustring (một dạng biểu thức chính quy kiểu Lua thân thiện với unicode); mặc định là true

Ví dụ:

• Đếm chữ 'a': "{{#invoke:String|count|aabbcc|a}}" → "2"
• Đếm số lần xuất hiện của 'aba': "{{#invoke:String|count|ababababab|aba}}" → "2"
• Đếm "hoặc 'a' hoặc 'c' ":"{{#invoke:String|count|aabbcc|[ac]|plain=false}}" → "4"
• Đếm "không phải 'a' ": "{{#invoke:String|count|aaabaaac|[^a]|plain=false}}" → "2"
• Đếm "bắt đầu bằng 'a' ": "{{#invoke:String|count|aaabaaac|^a|plain=false}}" → "1"

join

Nối tất cả các chuỗi được truyền dưới dạng đối số thành một chuỗi, coi đối số đầu tiên là dấu phân cách.

Cách dùng:

{{#invoke:String|join|dấu_phân_cách|chuỗi1|chuỗi2|...}}

Các tham số:

separator

Chuỗi dùng để phân tách từng chuỗi được nối với nhau

Lưu ý rằng khoảng trắng ở đầu và cuối dấu phân cách sẽ không bị loại bỏ.

string1/string2/...

Các chuỗi được nối với nhau

Ví dụ:

• "{{#invoke:String|join|x|foo|bar|baz}}" → "fooxbarxbaz"
• "{{#invoke:String|join||a|b|c|d|e|f|g}}" → "abcdefg"
• "{{#invoke:String|join|,|a|b|c|d|e|f|g}}" → "a,b,c,d,e,f,g"
• "{{#invoke:String|join|, |a|b|c|d|e|f|g}}" → "a, b, c, d, e, f, g"
• "{{#invoke:String|join| – |a|b|c|d|e|f|g}}" → "a – b – c – d – e – f – g"

Ví dụ trước sử dụng thực thể html – nhưng ký tự unicode cũng hoạt động.

endswith

Đối với hàm startswith, xem Module:String2 § startswith.

Cách dùng:

{{#invoke:String|endswith|chuỗi_nguồn|chuỗi_cần_tìm}}

HOẶC

{{#invoke:String|endswith|source= chuỗi_nguồn |pattern= chuỗi_cần_tìm}}

Trả về "yes" nếu chuỗi nguồn kết thúc bằng chuỗi tìm kiếm. Sử dụng các tham số có tên để cắt khoảng trắng của chuỗi trước khi sử dụng. Bất chấp tên tham số, chuỗi_cần_tìm không phải là mẫu Lua, nó được diễn giải theo nghĩa đen.

• "{{#invoke:String|endswith|xxxyyy|y}}" → "yes"
• "{{#invoke:String|endswith|xxxyyy|z}}" → ""

Xem thêm

• {{#invoke:Params|mapping_by_replacing}} và các hàm khác từ cùng mô đun này
• {{#invoke:MultiReplace|main}}