التابع IO.readpartial‎ في روبي

يقرأ التابع readpartial maxlen (انظر فقرة البنية العامة) بايتًا على الأكثر من مجرى د/خ. لا يقوم التابع readpartial بالتعطيل إلا في حال لم يكن في مجرى د/خ ios أي بيانات متوفرة آنيًا. لن يقوم بالتعطيل في حالة توفر بعض البيانات.

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

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

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

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

محتوى المجرى فارغ.

المجرى لم يبلغ محرف نهاية الملف (EOF).

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

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

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

إذا لم يكن المخزن المؤقت للبايت فارغاً، فسيقرء من المخزن المؤقت للبايت بدلاً من "القراء من المخزن المؤقت لمجرى د/خ IO (IOError)".

لا يتسبب في الخطأين Errno :: EWOULDBLOCK و Errno :: EINTR. عندما يصادف التابع readpartial EWOULDBLOCK و EINTR من استدعاء النظام read، سيحاول التابع readpartial إعادة استدعاء النظام.

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

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

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

المعاملات

maxlen‎

الحد الأقصى

outbuf‎

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

أمثلة

مثال على استخدام التابع 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: يقرأ كل الأسطر الموجودة في مجرى د/خ ios، ثم يعيدها في مصفوفة. يتم فصل الأسطر بالوسيط الاختياري sep (انظر فقرة البنية العامة). إن كان الوسيط sep يساوي nil، فسسيُعاد بقية المجرى كتسجيلة (record) واحدة. إن كان الوسيط الأول عددًا صحيحًا، أو إن أعطي الوسيط الاختياري الثاني، فلن تكون السلسلة النصية المعادة أطول من حيث عدد البايتات من القيمة المحددة. يجب أن يكون المجرى مفتوحًا في وضعية القراءة أو سيُطلق استثناء IOError.
• التابع reopen: يربط بين مجرى د/خ الذي استُدعي معه ios وبين مجرى د/خ المعطى في other_IO (انظر فقرة البنية العامة)، أو مجرى جديد يُفتح من المسار path. قد يؤدي هذا إلى تغيير الصنف الفعلي لهذا المجرى ديناميكيًا.

مصادر

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