Ruby/IO/readpartial

يقرأ التابع readpartial من مجرى د/خ maxlen (انظر فقرة البنية العامة) بايتًا على الأكثر .

لن يقوم التابع readpartial بالتعطيل (block) إلا في حال لم يكن في مجرى د/خ أي بيانات متوفرة آنيًا. أي أنه لن يُعطِّل في حالة توفر بعض البيانات.

في حال إعطاء الوسيط الاختياري outbuf (انظر فقرة البنية العامة)، فينبغي أن يشير إلى سلسلة نصية، والتي ستتلقى البيانات. لن يحتوي الوسيط outbuf إلا البيانات المستلمة بعد استدعاء التابع، حتى لو لم يكن فارغاً في البداية.

يُطلق التابع readpartial الاستثناء EOFError عند نهاية الملف.

صُمِّم التابع readpartial لأجل المجاري (streams) من مِثل الأنابيب (pipes)، والمقابس (sockets)، والطرفية tty، إلخ. ولن يقوم بالتعطيل إلا عند عدم توفر أية بيانات فوريا. هذا يعني أنه سيُعطّل فقط عند تحقق جميع الشروط التالية.

• ذاكرة التخزين المؤقت للبايت (byte buffer) في مجرى د/خ فارغة.
• محتوى المجرى فارغ.
• المجرى لم يبلغ محرف نهاية الملف (EOF).

عندما يقوم التابع readpartial بالتعطيل، فإنه ينتظر البيانات أو محرف نهاية الملف EOF من المجرى. فإذا حصل التابع readpartial على بيانات، فسيعيدها. أما إذا وصل إلى محرف نهاية الملف، فسيُطلق الاستثناء EOFError.

عندما لا يقوم التابع readpartial بالتعطيل، فسيقوم بالعودة، أو يطلق استثناء على الفور. وإذا لم يكن المخزن المؤقت للبايت فارغًا، فسيُعيد البيانات الموجودة في المخزن المؤقت. وإلا إن كان في المجرى بعض المحتويات، فسيعيدها. خلا ذلك، إذا وصل المجرى إلى محرف نهاية الملف، فسيطلق الاستثناء EOFError.

لاحظ أن التابع readpartial يتصرف بشكل مشابه للتابع sysread. لكن مع الاختلافات التالية:

• إذا لم يكن المخزن المؤقت للبايت فارغاً، فسيُقرء من المخزن المؤقت للبايت بدلاً من القراءة من المخزن المؤقت لمجرى د/خ كما يفعل sysread.
• لا يتسبب في الخطأين Errno::EWOULDBLOCK و Errno::EINTR. عندما يصادف التابع readpartial الخطأين EWOULDBLOCK و EINTR الناتجين عن استدعاء النظام read، سيحاول إعادة استدعاء النظام.

هذا الأخير يعني أن التابع readpartial غير حساس لقيمة الراية nonblocking. سيقوم بالتعطيل في الحالات التي يقوم فيها التابع sysread بإطلاق الخطأ Errno::EWOULDBLOCK، كما لو كان fd (واصف الملف) في وضع التعطيل (blocking mode).

البنية العامة

readpartial(maxlen)  → string
readpartial(maxlen, outbuf)→ outbuf‎

المعاملات

maxlen‎

عدد صحيح يمثل الحد الأقصى

outbuf‎

سلسلة نصية تتلقى البيانات

القيمة المُعادة

يعيد التابع readpartial السلسلة النصية المقروءة.

أمثلة

مثال على استخدام التابع readpartial‎:

r, w = IO.pipe           #               buffer          pipe content
w << "abc"               #               ""              "abc".
r.readpartial(4096)      #=> "abc"       ""              ""
r.readpartial(4096)      # blocks because buffer and pipe is empty.
r, w = IO.pipe           #               buffer          pipe content
w << "abc"               #               ""              "abc"
w.close                  #               ""              "abc" EOF
r.readpartial(4096)      #=> "abc"       ""              EOF
r.readpartial(4096)      # raises EOFError
r, w = IO.pipe           #               buffer          pipe content
w << "abc\ndef\n"        #               ""              "abc\ndef\n"
r.gets                   #=> "abc\n"     "def\n"         ""
w << "ghi\n"             #               "def\n"         "ghi\n"
r.readpartial(4096)      #=> "def\n"     ""              "ghi\n"
r.readpartial(4096)      #=> "ghi\n"     ""              ""‎

انظر أيضا

• التابع readlines: يقرأ كل الأسطر الموجودة في مجرى د/خ، ثم يعيدها في مصفوفة.

مصادر

• قسم التابع readpartial‎ في الصنف IO‎ في توثيق روبي الرسمي.